Finder & Applications 
Our group is doing four kinds of projects for Big Bang. 


First of all, we’re doing user interface, bug fix, and cosmetic improvements to existing 
software. This includes updating LaserWriter Font Utility to support the Kanji LaserWriter 
(LaserWriter Font Utility 2.0), imrpoving CloseView for sighted users (CloseView 1.1), 
MacroMaker with an improved user interface (MacroMaker 1.1) and new versions of vari- 
ous desk accessories. 


Second, we’re doing support for specific hardware. This includes the Esprit control panel, 
the Battery desk accessory, and the Topanga video control panel. 


Third, we’re doing to major projec aimed at Enprne the Macintosh user experience, 
Installer 3.0 and iiss . The new y ed-bath to make the first 
few moments with the Macintosh a better ex pur installation to 
span more than one disk 5 2000,}the p e Finder’s direct ma- 
nipulation interfa eatures that ¥ Out the system previous- 


ly, including moving {efi sessories and sounds, A functions of the 


sede programming res 


Some of our specifications are more complete than others, but I hope you'll find most of 
them interesting. 


Darin 
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Introduction 


This document describes the new Installer version 3.0. This new Installer has three main goals: 1) 
to allow for multi-disk installations, 2) to address complaints that ¢ customers have with the current 
Installer, and 3) to enhance the Installer) by DO oviding a le erface. A fourth goal would be 


approximately in order pf i ance/priority as we see things, Yen go into some of the issues 
and reasons behind thege . Many\of these requiréments/dictate changes to the present 
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we OWS 
Requirements 


To accomplish our three main goals, we have addressed many different issues. Here is a summary 
of the areas we have changed for the Altair System release. 


Multi-Disk Installation - System Tools releases will soon be larger than what fits on a standard 800K 
floppy disk. Because of this, the driving requirement for a new version of the Installer is the 
ability to install files and resources from more than one disk. The novice Macintosh user should 
have available a simple, painless way of installing all of the system software (including printer 
drivers) from 2 or more floppy disks onto his or her new system. Version 3.0 must support this 


requirement. 
Reduce Disk Swapping - If installing System Tools Version 5.0 on a Mac Plus with a single floppy 


drive, over 300 disk swaps are required for the operation. In order to decrease our liability, 
(Macintosh Owner Goes Stark Raving Mad — Sues Apple) Installer version 3.0 will maximize 
utilization of system memory to minimize the ber of disk swaps needed for installation. 


izes’  epune S ZeS . ee wait, wait) wait), choose 
pave apmoyed by this curious 


e Installer is the 


Staller assumg l users of the program 
have similar levels of expertise aad new Mac user warts to sifnply "press a button” (Just 
‘Say Go!) and have all of t : softer e installed. The ag user may want to know 
more specifics on which ff resourges are bging installgd and hgve more choices as to what 
gets installed. Any improvéments in the user-jaterface shoufd addregs this difference in needs. 


Context Intelligent Installation - As the number of different types of Macintoshes and hardware 
configurations increases, machine or hardware specific installations will also increase. The 
Installer should be smart enough to know what the target machine will be, and provide appropriate 
defaults for that machine. 


Installation Over AppleShare - We should allow users to run the Installer from an AppleShare file 
server. At the very least, the application should be “sharable,” the scripts should be able to handle 
finding sources on an AppleShare volume, and the source files and resources for an installation 
should be able to be placed on an AppleShare volume. If time permits, it would be nice if the 
Installer could update running systems over AppleShare. This is a difficult problem. 


. Provide More Information - The first time Macintosh user doesn't need to know exactly what is 
being installed, but the more experienced user probably will want to know the versions, creation 
dates, and sizes of the files and resources which can be installed. Some of this type of information 
is available with the current Installer. The new Installer should provide more of this type of 
information. 


Leverage Off New ROMs - It is assumed that new versions of the Installer will run only on machines 
with new ROMs and HFS. Much of the current Installer code can be streamlined and optimized 
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for this environment. 


Provide More Help to the User - The new Installer should provide more complete help to the user of 
all screens. 


- Everyone and their mother has ideas about what the installer 
of the future will look like and do. There are two parts of the installation pie — the user interface 
part and the "guts" part. If we can reduce the coupling between these two parts, and provide a 
robust and semi-complete set of routines to access the "guts," it will be much easier to develop 
new and better user-interfaces. 


aw 
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Terminology 


A new term that we are introducing as part of our proposal is the term package. A package is a 
logical group of files and resources that the user can choose to install. Examples of packages are "Mac 
II System", "LaserWriter IISC", "AppleShare". These roughly equate to a script file under the current 
Installer. The files and resources that make up packages are all defined in scripts. (See section on 
scripts.) 
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“User Interface Description 


Our changes to the user interface support the goal of providing a leveled interface where we 1) 
provide a simpler interface for the novice user which consists mainly of choosing a disk and clicking 
Install; and 2) provide the current Installer interface with minor improvements for the more experienced 
user. In both of these interfaces we will provide the user with more help. 


The screen shots that we are presenting represent the Human Interface recommendations for the 
Installer. They incorporate the ideas and feedback from many brainstorming sessions, ERS review 
meetings, and Human Interface User Testing using Hypercard prototypes. 


Initially, when the user runs the Installer, a splash screen comes up giving the user helpful 
information about what the Installer does and explaining the difference between the screens. This screen 
is not fixed by the Installer, it comes from a ‘PICT’ resource in the script file. We encourage script 
developers to take advantage of this splash screen to introduce the user to the software being installed. 
(See section on scripts for more detail.) 


Installation . 
start up into the Folder. Theré are Awo options: 


e Easy Instal pis-p your syste ith the 
appropriate system and ‘be printer 
software for your Macintosh and puts 


it in your (G) System Folder. 


e Custom Install Allows you to select which software 
you want to put into your System Folder. 


3.0d1 


The simpler screen, which we are calling the "Easy Install" screen, only comes up if there's an 
appropriate "default map script” available (see section on scripts). Apple's Installation scripts for 
System Software will always have default maps and we will encourage third party developers of 
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Installer scripts to also take advantage of the leveled interface by providing default maps for their 
scripts. 


Easy Install 


Click on Install to place: 


e Mac Family Minimal System Software 
Version 6.0.2 | 
e ImageWriter Printer Software 


on the floppy disk named 
blah 


Eject Disk 


Using the "default map" the Installérdetermines (based on the selected disk and the hardware 

+ configuration of the current machine) which are the default "packages" to install. The description of 

what will be installed is displayed (in this case "Universal Macintosh System 7.0" and "All Printers") in 
the form of instructions to the user ("Click on Install..."). This screen lets the user select which disk to 

’. install.on, however it does not let the user install other than the default packages. 


To install something other than the default, the user needs to click on the "Custom..." button. This 
will bring up the "Custom Install Screen": 
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Custom Install 


Mac Il Family System Software 

Macintosh SE System Software 

Macintosh Plus System Software Jastal 
Macintosh Family System Software 

Minimal Mac I! Family System Software 

Minimal Mac SE System Software blah 
Minimal Mac Plus System Software — 


Minimal Mac Family System Software Eject Disk 


Switch Disk 


with each of the script files no Iomger appear in the scroll box, instead the names of all the packages that 
the Installer found in the script file are displayed. To select a package for installation requires selecting . 
that package by clicking on it. This interface supports multiple, discontiguous selections by using Shift- 
click to make selections. It also lets the user drag the mouse to select multiple contiguous selections... 
Any or all of the packages listed can be selected. Unlike the current Installer, the user is never told the..’ 
amount of disk space that will be taken up as a result of an Install. The sizes are always figured but it is 
put off until the user clicks "Install". At this point if the Installer determines that all the selected items 

won't fit, the Installer will alert the user. ae 


There is no Remove button on the Custom Install screen. It was decided that the Remove option 
was rarely used and was only used by advanced users. To remove a package or packages, hold down the 
Option key while clicking the Install button. When the Option key is pressed, the Install button becomes 
a Remove button (only on Custom Install screen). 


The Get Info feature allows the user to get more information on a particular package. Whenever 
only one package is selected, the Get Info information is displayed in the message area in the lower left 
corner of the screen. This info is similar in format to the Get Info information available in the Finder. 
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Custom Install 
Mac Ii Family System Software 
Macintosh SE System Software 
Macintosh Pius System Software 
Macintosh Family System Software 

Minimal Mac II Family System Software 

Minimal Mac SE System Software blah 
Minimal Mac Plus System Software 


Minimal Mac Family System Software | Eject Disk 


_ Mac II Family System Software Switch Disk 
==, Package Size: Need to figure sizes | 

Release Date: Thu, May 19, 1988 

Release Version: 6.02 


This package contains a domplete set of System Softwhre for 
: use on the Macintosh Il. [t also contains the mjnimal spftware 
i needed to startup on all Yersp @ Macintosh. 


CO naccrecececececwesoernosasecenosenesooeeccetcusose 


. 
Pere ee rere rrr oer ror ore Se er oy 


To get help on the "Easy button. This displays some 
help text in the lower left of : ore” button allowing the user 
to get the next "screenful” of . Thé help messgge tells fhe user the function of each of 


a "Done" button which needs to be clicked to get rid of the Help text. - 
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Easy Install 


Pereira err errrrrrirrrrrrrirerttrirrrrrrs 


Click on Install to place: 


e Mac Family Minimal System Software 
Version 6.0.2 
e ImageWriter Printer Software 


on the floppy disk named 
blah 


Prrrrrrrr rire or rrr rrrrririrerirrrrririterrrrrr rr rrr rrr rs 


If you want to install on a different disk, 
click Eject Disk or Switch Disk to 
find the correct disk. 


Redon cceccancecccescrsccenenocenenacenrnscoeseus 


Anstall screen. 


: g g Il be in alerts put up in front of either 
screen. During installation, the status information will be similar to that of the Finder when files are 
being copied. It will have a cancel button, it will show a status bar, it will show the percentage 
completed, and it will show which file or resource is currently being copied. 
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Installer Script Modifications 


The following section describes the modifications to the format of an installer script needed in 
version 3.0 to support the new user interface. We are making the following basic changes to scripts: 1) 
the addition of a whole new type of script resource that specifies which defaults appear in the "Easy 
Install” screen, 2) a change to the current script’s format so that files and resources are specified in the 
form of “atoms” and lists of these atoms are broken down into packages and 3) we will work from only 
one installer script file. This one script file will contain all the information needed to install from a 
multiple disk software release. 


A script is a list of instructions (in the form of resources) for the Installer. In earlier versions of the 
Installer, scripts were wholly contained in resources of type ‘insc.' In version 3.0 of the Installer, several 
new types of resources are used for these instructions. In a typical script, these resources might logically 
be arranged in a hierarchy like this: 


_—< | 


Subpackage Subpackage 


Package 


Subpackage 


The first of these new resources is the default map or 'indm' resource. The purposes of the default 
map are to provide information to the "Easy Install" screen interface and to give default software 
requirements for specific hardware. It can be thought of as a mapping between a specific hardware 
configuration and a set of software to be installed. First time Macintosh users do not want to be 
concerned with knowing the configuration of their systems. A default map defines the sets of files and 
resources ("packages") that are most likely to be installed on a specific machine. It also provides some 
of the text used in the "Easy Install" screen. An example default map might specify that on the internal 
hard drive of a Mac II with 2 M of memory, we should install the Mac II system software, and all printer 
drivers. 


Default maps specify the set of files and resources to be installed by specifying a set of packages 
(resource type ‘inpk'). Packages contain lists of related files and resources. Packages have names, 
associated comment resources, and a list of components including file atoms and resource atoms. 
Typical packages might be: "Mac II System Software or "EtherTalk Files and Resources." 


In addition to atoms, packages may also contain subpackages in their list of components. 
Subpackages are identical to packages. They are provided for the convenience of the script developer 
since several packages may use the same subpackage. Several packages such as "Macintosh II System" 
and "Macintosh SE System" for example, might both contain the subpackage "MultiFinder” which in 
turn contains the file atoms "MultiFinder," "DA Handler," "BackGrounder," and "Finder StartUp." 
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In the hierarchy of new resources, atoms (resource type 'infa’, 'inra', and 'inbb’) are at the lowest 
level. Atoms come in three flavors, file atoms, resource atoms and boot block atoms. These specify 
single resources or files to be installed or deleted as part of an installation or boot block values that need 
to be changed. Note that atoms are not visible to the user of the Installer program, therefore all atoms 
will be contained in either packages or subpackages. In earlier versions of Installer scripts, the atoms 
were listed together in either the "File List" or the "Resource File List." In version 3.0, each of these 
files and resources is specified in a separate atom. This allows more flexibility within packages (several 
packages may share the same atom) and it will be easier to modify individual atoms. The information 
contained within the file and resource atoms is basically the same as that found in the old Installer script 
File Specs and Resource File Lists. 


The information in the following sections will be important for those interested in writing scripts. 
Those interested only in the user interface can safely skip them. 


Default Maps 

To support the Easy-Hrs ereerarid intellige ype of Installer Script 
resource has been creat¢d — the default map{or 'indmm’ resource. The purpose of an 'indm' resource is to 
provide the Installer with inform bout which files 1 be installed when certain 
types of hardware or software are fo 1d. These de asy Install" screen. The format 
of the default map is shown go default map existsAvithiff a script the Custom Install. 
screen, not the "Easy Ingtall" sereem is displayed when the program ig launched and the "Easy" button 
on that screen is not visHele , this will be rare sinc¢ Appl¢ will always include a default map 


with its system software updates and we encougage third pgfty script writers to use default maps. 


resource ID, a User Description-andertist of packages. 


The Installer chooses the appropriate packages to install by going through an ordered list of Default 
Maps. The Installer searches through the default maps (lowest resource ID to highest) until it finds a 
map which matches the hardware and software configuration of the machine it is running on, and the 
size of disk that has been chosen by the user. When the first match is found, the User Description field 
of the map is displayed on the Easy Install screen. If the user then clicks on the "Install" button all of the 
packages listed in the map's Package List will be installed. Whenever the user chooses a different disk, 
the list is searched again from the beginning for a new match. 


Because the list is ordered by resource ID, the most stringent requirements for an installation should 
be put in maps with lower resource IDs. For example, if a special set of packages is available for 
Macintosh IIs with an MMU, and a different set is to be used on machines without one, the default map 
for the MMU installation should have the lower resource ID. 
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Default Map 


Default Map Flags (2) 


User Description (pstr) 


Package List 


HW Requirements 


Number of Machines (2) 


EE. 
| Pecssortee Lh 
Numberof MMUs 7 ~\ (2) 


3 
<—— 
Number of Keyboards ( 


Keyboard Type (2) 


Requires FPU (1) 
Requires Color QD (1) 
Minimal Memory (2) 


Figure 1. Default Map 


Default Map Format Version 


The Default Map Format Version field (2 bytes) is an unsigned integer indicating the version of the 


RumberofPeses | [saat — [Sysdaxvisin “7” 7” al 


Package List 


Number of Packages (2) 
Package ID 


SW Requirements 


Number of System Resources (QQ) 
| Sysfem Resource Spec__ |_| 


\ Country Code 
| AppleTalk Driyér Veryfon___(2)) 


Resource Type - (4) 


Resource ID (2) 


Default Map script format. It is currently 0. If the Installer encounters a default map with a version 
higher than it knows how to handle, the map will be ignored. 


Default Map Flags 
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asa 


The Default Map Flags field (2 bytes) consists of 16 bit-flags. They are currently unused and should 


be set to 0. 


HW Requirements 


Information about the minimal hardware needed to install a specific package is contained in the HW 
Requirements field. There are seven fields in the BeSrIEHOD of the hardware requirments, four of 


which are lists. 


A value of 0 in any of these fields, or a list of length 0 indicates that you don't care about that 
configuration. For example, if an installation does not depend on the type of Keyboard being used, that 


list should be empty. 


The description of these fields is as follows: 


Number of Machines: 


Machine Type: 


Number of Processors: 


Processor Type: 


Number of MMUs: 


MMU Type: 


Number of Keyboards: 


Keyboard Type: 


Requires FPU: 


The number of machines in the Machine Type list. 


The Machine Type field is list of 2 byte values which 
pagan the machines a this default map. The values 
~same-as found in the machineType 


The MMU Type field is list of 2 byte values which 
specify the MMU for this default map. The values for 
this field are as follows: 


0: GMMU 
1: 68851 
2: 68030 


The number of keyboards in the Keyboard Type list. 


The Keyboard Type field is list of 2 byte values which 
specify the keyboards for this default map. The values 
for this field are the same as found in the 
keyBoardType field returned from SysEnvirons. 


The FPU field is one byte, whose lowest ordered bit is a 
flag that specifies whether an FPU is needed for this 
default map. 
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Requires Color OD: The Color QD field is one byte, whose lowest ordered 
bit is a flag that specifies whether color QuickDraw is 
needed for this default map. 


Minimal Memory: The Minimal MemoryType field is a 2 byte quantity 
specifying the minimal amount of RAM (in MBytes) 
needed for this default map. 

SW Requirements 

Some installations may be dependent on the existence of certain resources in the System file. For 
example, when updating a system, it is necessary to know the patches which have been previously in- 
stalled on the target system. The Installer looks at the System file in the blessed folder on the chosen 
target volume and compares the following fields to the values found in the System’s resource fork. 


Number of System Resources: The number of resource specs in the System Resource 
Spec list. 
m Resource Spec: The System ReSOUlce aunts is a list. Each entry in the 


a-HOSOUTCe to search for 


System Revision: i ith fie minimal system revi- 


| Country Code: | © field if a 2 byte field indicating 


ystem for this default map. This 
number has the same format as in the intlOVers field of 
a IntlORec record. This information will come from the 
‘vers’ resource in the target volume’s System File 


AppleTalk Version: The AppleTalk Version field is a 2 byte field which 
indicates the lowest numbered version of the AppleTalk 
drivers needed for this default map. It has the same 
format as the System Version field. 


Target Volume Requirements 
The Target Volume Requirements field (8 bytes) contains information about the requirements for a 
target disk drive. It contains 2 fields: 


Minimal Target Size: The smallest size disk (in k) this default map will use. 
Maximal Target Size: The largest disk (in k) for which this default map is ap- 
| : plicable. 
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To match any size disk, the minimal and maximal target disk sizes are both zero. If the Minimal 
size is greater than zero but the Maximal equals zero, then only the minimal requirement will be used. 


User Function 

The User Function field contains the ID of an "infn" resource. This type of resource is an 
executable Macintosh function which returns a Boolean value. We pass to this function the volume ref- 
erence number of the currently selected target disk. The declaration for such a function and its 
parameters would look something like this in Pascal: 


FUNCTION My!INFNCvVRefNum: Word): BOOLEAN; 


If this field is non-zero, the infn will be executed and its return value "anded" with the hardware 
requirements and target disk type results. If the field contains zero, no infn will be executed. We 
anticipate that this user defined function might be used to determine the existence of specific hardware 
such as accelerator boards, video cards, or network interfaces. — | 


User Description 
The User Descriptipn : | Pascal Ting aller q 


isplays on the "Easy Install 


The description should inicate¢he conf} duloicee thgt is being installed. Examples might be: "* Mac 
: r "the Mac II colof monitor version of MegaPaint." Note 

that no parsing of this field 1s tone: erating such as carnage returns are desired, they must be 

inserted into this string where appropriate. 


Package List 
The Package List field is a list of all the packages associated with this default map. It contains the 
number of packages in the list, and the resource IDs of the packages. 


Packages 


Packages are used to group logical sets of resources and files to be installed. These sets are seen by 
the user in the Custom Install screen. Every default Map contains a list of packages. Packages have a 
resource type ‘inpk.' The format of a package can be seen in Figure 2. 
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Package Parts List 


Package Format Version (2 


Package Flags 
ICMT ID 


Number of Part Specs (2) 


Package Size 4) | 
Package Name (pstr) Parts Spec 
ean 0 


Part ID (2) 


Figure 2. Packages 


Packages are listed in the Custom Install screen in the order that they appear in the resource file. A 
package contains 5 fields, a Package Format Version field, a Package Flags field, the Package Name, an 
identifier for an Installer Comment, and a Parts List. 


Package Format Version 


The Package Format Versipn f: is dn unsigned integer indicating tle version of the 
package format. It is currentlyjO. If the Installer egcountefs a Packa a higher version 
number than it currently know ho € packa j 
Package Flags 

The Default Map Flags fie}d ( gnsists of\16 bit-flags. ¥ only the high order bit is 


used. This bit is set if the package should shqw up in the list of pagKages gvailable on the Custom Install 
screen; otherwise the bit is cleat" 


displayed when one package is selected in the Custom Install screen.. If the value in this field is 0, a 
default Installer Comment is created using the name of the package, the creation date of the script file, 
and the package's size, but without a version, or comments. (See the ICMTS section below for a further 
description of this resource.) Note that if the packages is not going to be visible on the Custom Screen 
(according to the bit-flag in Package Flags) there is no need for an ICMT. 


Package Size 

The Package Size field (4 bytes) contains the size all the files and resources that are to be copied as 
part of the installation of this package. The value for this field is the sum of all of the atom size fields in 
the resource and file atoms which have their copy bit set. We are providing a script preprocessor that 
will figure out the value of this field. This field is used to display the package size in an ICMT. 


Package Name 

The Package Name field is an even-padded Pascal string that the Installer displays in the list of 
packages available in the Custom Install screen. It is also the name that appears in the informational 
rectangle in Custom Install. The Package Name should indicate what the package contains and the 
version number. Examples are "Macintosh SE System 7.0" or "LaserWriter IISC 8.0." 


Parts List 
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The Parts List is a list of all the file atoms, resource atoms, boot block atoms, and possibly other 
packages associated with this package. It consists of a Number of Part Specs field followed by one or 
more Part Spec fields. 


Number of Part Specs 
The Number of Part Specs field (2 bytes) is an unsigned integer specifying how many Part Specs 
follow it. 


Part Spec | 
A Part Spec specifies either another package (subpackage) or a file, resource, or boot block atom to 
be deleted or installed. It consists of two fields: a Part Resource Type and a Part Resource ID. 


Part Resource Type 

A Part Resource Type (4 bytes) specifies the resource type of the part. The resource type should be 
either an ‘inpk' (indicating a subpackage), an '‘infa' (indicating a file to be copied or deleted), an 'inra' (a 
resource to be installed or removed), or an ‘inbb' (a boot block parameter that needs to be changed). 


Part ID 
A Part ID (2 bytes) ppeetftes-the-reseturc¢ id of the-part 


Many times users KE now mote about a packagé are considering installing. We are 
proposing that users be able/to "Get Ir¥o" abou packages. Ths infofmation is displayed in a small 
rectangle and contains the-same of the package] its creationAlate, itf size, its version, an icon, and 
Resources (type ‘icmt'). The name 


The format of an installe is Shown in Figure 3. An ‘icmt' contains four fields, the Version 
Release Date, Version number, an Icon ID, and Comment Text. 


Version Release Date (4) 


Version 
Icon ID (2) 


Comment Text (pstr) 


Figure 3. icmt Format 


Version Release Date 
This 4 byte field contains the date in GetDateTime format. It will appear in the "Release Date” field 
in the Get Info message area. 


Version 
The Version field (4 bytes) contains the version number of this package. It has the same format as 
the systemVersion field of a SysEnvRec record. 
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Icon ID 
The Icon ID field (2 bytes) contains the ID of an ICON resource. This icon will be displayed in the 
upper left corner of the Get Info message area. 


Comment Text 
This even padded Pascal String contains the text which will appear in the comment section of the 
Get Info message area. 


Atoms 

Atoms are at the lowest level in the hierarchy of default maps, packages, subpackages and atoms. 
Atoms come in three flavors, File Atoms (‘infa'), Resource Atoms (‘inra'), and Boot Block Atoms 
(‘inbb'). Each atom represents a single file or resource to be installed or removed or a boot block 
parameter to change. Atoms cannot be installed by themselves, they must be part of a package or 
subpackage. Both File and Resource Atoms contain respectively a File Size and a Resource Size field. 
We are providing a script preprocessor tool to fill in these fields of the scripts. 


File Specs 
Both File Atoms and Resourcq Atoms refer to File Specs. | more info 


lation on the file that 


File Name (pstr) 


Figure 4, File Specs 


File Type 

The File type field (4 bytes) specifies what the file's type is expected to be. This field may be 
ignored based on the value of the type and creator must match bit flag of the File Spec Flags. This field 
is to help ensure that the correct file is being used. 


File Creator 

The File Creator field (4 bytes) specifies what the file’s creator is expected to be. This field may be 
ignored based on the value of the type and creator must match bit flag of the File Spec Flags. This field 
is to help ensure that the correct file is being used. 
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Creation Date 

The Creation Date field (4 bytes) specifies what the source file's creation date is expected to be. If 
this field is 0 then the Creation date of this file will be ignored. If this field is non-zero, the file on disk 
will not be recognized as the correct file unless its creation date matches the date in this field. This field 
is to help ensure that the correct file is being installed. For a target file specs this field is ignored. 


File Name 

The File Name field is an even-padded Pascal string that specifies the complete pathname of the file. 
Specifying the file’s name and path is different depending on whether you’re specifying a source or tar- 
get file. For a Source File Spec, the File Name field should contain a complete pathname of the file be- 
ginning with the volume of the given file and specifying the folder names in the path to the file. 


In a Target File Spec, the File Name field contains a modified partial pathname. Because the target 
volume name is not known at the time a script is written, the script writer specifies a partial pathname 
that begins in the root directory of the target disk. Also, because the "blessed folder" can have any name 
and be nested within other folders, the keyword "Blessed" is used to denote the pathname of the blessed 
folder on the target disk. If a blessed folder does not exist, it will be created off the root directory and be 
called "System Folder." This means that if the fully qualified Sere to the system file on the target disk 
was "MyVolume:MyFokles embdlder:S ystepa--then-the dK lessed" would be expanded 
by the installer to be " yVolume: MyFoldey MySys emFolder. i In use, if yu wanted to put the file 
"MultiFinder" in the blegsed fe 
"Blessed:MultiFinder." {If alfolder in the pathnanse j ist, the in Aller will create one. For 
scriptwriters this means|thatpyou will nofbe able to install or dele i€ or a resource within a file that 
is in a folder that is actuplly ngmed\Blessed’\ (This really sho hn’ tYea problem. If it is, see the sec- 
tion on localization.) Te spgci arxet file ndt in the blessed foldef just give a partial pathname begin- 
ning with a colon (e.g. “file 


Because of the m ; foility, the gemantigs of the File Name field are a bit com- 
plex. Customers may Haye copiet the dist Wution disks hard disks and want to install from 
there, or they may have mat ’ disks provided by Apple and expect to 
be able to install from those. In eithert case, the pathname specified in the File Name field of the Source 
File Spec will probably be slightly off (e.g. the backup disks may not have the same names as the 
originals) so we need to be somewhat flexible when searching for a specific source file. In a Source File 
Spec, the full path name (including volume name) must be given in the File Name field, but it may not 
be used by the Installer exactly as given. 


While the Installer is flexible as to exact volume names, it requires that disk contents be the same as 
what is specified in the script. The Installer uses the scripts to make a list of the volumes that will be 
needed for the Install and the files that should be on each volume. All the files that are supposed to be 
on the same volume, must be on the same volume. But that volume’s name can be different from the 
name given in the script. In addition we will relax this condition only slightly to allow for hard disk in- 
stallations. You can have more than one volume’s worth of contents on the Installer disk. We will 
allow these files to either be relative to the root of the Installer volume or relative to the Installer’s direc- 
tory. For example if the Installer is in the folder “Installer Folder’ on the hard disk “My HD” and the 
script wants files from the folder “Utilities 2:System Folder Additions” then that folder could either be 
exactly where specifed, on the root of the “My HD” disk, or in the “Installer Folder” on “My HD”. 


The disk that the Installer is on is a special case in our requesting disk and disk content strategies. Most 
of the disks are requested in alphabetical order, but the Installer’s disk is always the first disk that we 
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copy files and resources from. Also the contents of the installer disk is checked for correctness before 
anything is deleted or copied. We recommend scriptwriters (especially for system releases) have the 
most important files and resources to be copied on the Installer disk, since that’s the only disk that we 
can guarantee that the user has. Otherwise, the Installer could start the installation which includes delet- 
ing all the appropriate target files and resources, ask for a disk that contains a crucial file, have the user 
cancel out of the dialog since that disk for some reason is not available thereby aborting the installation 
leaving the user worse off than before (e.g. a system that no longer boots). 


Sometimes it is desirable to update a file on a target disk, but its location may not be known. For 
example, we may need to update a utility application, but it could be anywhere on the target disk. To 
meet this need, one of the bit-flags in the File Spec Flags field is a search flag. If this flag is set, the 
Installer will look for the file first in the given pathname. If it is not found there, a search of the entire 
volume will be performed for that filename. The search stops when an instance of the file is found or 
the whole disk has been searched (therefore the first found will be the only one affected—this flag 
should be used with care). If the flag is not set, the file must be found in the given pathname. 


File Spec Flags 


The File Spec Flags field is a 2 byte field co 


ining 16 bit flags. The meaning of the bits is 
described below. 


15 14 13 12 11 10 


[lJ 10} yorwas 


g$ 
Figure 4, File Spec Flags 
bit 0: type & creator must match; if this bit is 1 the file type & creator of the file on disk must 
match what is specified in the file spec of script. 
bit 1: search for file; if this bit is 1 then the file should be searched for if not found in the given 


path. See description in above paragraph. This is always 0 for source file specs. 


File Atom 


The format of a File Atom is shown in figure 5. It contains six fields. 
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File Atom 


File Atom Format Version (2) 
File Atom Flags (4) 


Target File Spec ID (2) 
Source File Spec ID (2) 


File Size (4) 


File Atom Description (pstr) 


Figure 5. File Atoms 


File Atom Format Version 

The File Atom Format Version field (2 bytes) is an unsigned integer indicating the version of the 
file atom format. It is currently 0. If the Installer encounters a File Atom Format with a higher version 
number than it currently knows how to haadlg, the atom will be ignored. 


Target File Spec ID 
The Target File Spe 


Source File Spec ID 
The Source File Spe 
copied onto the target djek: 


File Size 

The File Size field (4 
by the Installer in figuring the Sfze 
compute the size to put in the script. 


fOr an installation. We are providing a script preprocessor tool to 


File Atom Description , 

The File Atom Description field is an even-padded Pascal string describing the atom. Possible uses 
for this field include showing it as part of the status feedback, including it into a log resource that shows 
the history of what was installed, or having it linked into the Get Info mechanism. 


File Atom Flags 
The File Atom Flags field is a 4 byte field containing 32 bit flags. The meaning of the bits is 
described below. 
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Figure 5. File Atom Flags 


bit 0: 

bit 1: 

bit 2: 

bit 3: 
bits 4-27: 
bit 28: 
bit 29: 


bit 30: 


bit 31: 


update only; if this bit is 1 and the target file does not exist then the source file will not be 
copied to the target disk even if copy (bit 13) is 1. 

keep existing; if this bit is 1 and the target file already exists then the source file will not be 
copied to the target disk even if copy (bit 13) is 1 

data fork; if this bit is 1 then the data fork of the file will be copied or deleted. 

resource fork; if this bit is 1 then the resource fork of the file will be copied or deleted. 
reserved; should be pees as 0. 

deferred delete; curres : 


delete on remove; if this 
target file will be deleted. 
ignored. 


Resource Atoms 
The format of a Resource Atom is shown in Figure 7. It contains 10 fields. The meanings of the 
fields are described below. In this Instaler, any file may be used as the source or target of a Resource 


Atom. 
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Resource Atom 


Resource Atom Format Version (2) 


Resource Atom Flags (4) 


Target File Spec ID (2) 


Source File Spec ID (2) 
Resource Type 


copied into the target file. 


Resource Type 
The Resource Type field is a 4 byte field that specifies the resource type (e.g. 'PTCH’) of the 
resource referred to by this resource atom. 


Source ID 

The Source ID field (2 bytes) specifies the resource ID in the source file. This field will be ignored 
if we're finding the resource by name (the find by id bit is 0) or if we're not copying the resource (the 
copy bit is 0). 


Target ID 

The Target ID field (2 bytes) specifies the resource ID in the target file. When copying a resource, 
the Installer will try to use this ID in the target file, but if there are ID conflicts the Installer will choose 
a different ID. If the ID of the resource doesn’t matter (e.g. most Desk Accessories) then this field 
should be specified as 0 and the Installer will pick an ID for the resource in the target file. 


Resource Size 
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The Resource Size field (4 bytes) is a longint containing the size of the resource to be installed or 
deleted. This size includes any resources that belong to the given resource (owned resources). This 
field is used by the Installer in figuring the sizes for an installation. We are providing a script preproces- 
sor that will figure out the value of this field. 


Resource Atom Description : 
The Resource Atom Description field is an even-padded Pascal string describing the atom. Possible 


uses for this field include showing it as part of the status feedback, including it into a log resource that 
shows the history of what was installed, or having it linked into the Get Info mechanism. 


Resource Name 

The Resource Name field is an even-padded Pascal string that gives the name of the resource. If the 
resource is being found by name (find by id bit is 0) it must be non-empty. To help ensure that the 
correct resource is being installed, the name of the resource in the source file must match this field if the 
resource is being found by name. Also the name of the resource in the target file must match unless the 


name must match is 0. 


Resource Atom Flags 
The Resource Atom Flags field 
described below. Many of the 
as unused for other resources. 


aning of the bits is 
need to be specified 


31 30 29 28 27 26 


& & 8 2 go gS 8 fs 
ee 8 g s Ye 2 3/2 
g g g. Ba & & BI & 
s F & ss § 2 & 8 
22 8 Be FE EE 8 
a F : es & 2~¢ 8 & 
i) g a. 
-15 14 13 12 11109 8 7 6 5 4 3 21 0 
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so) ~ - cc. = 
gs 2 2 & 
a S 
Figure 8. Resource Atom Flags 
bit 0: update only; if this bit is 1 and the resource does not exist in the target file then the resource 
will not be copied to the target file. 
bit 1: keep existing; if this bit is 1 and the target resource already exists then the source resource 
will not be copied to the target disk. 
bit 2: name must match; if this bit is 1 the name of the resource in the target file must match the 


name in the Resource Name field; this field is ignored if finding by name (find by id bit is 
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0). 


bit 3: find by id; if this bit is 1 then the resource will be found in the source file by using the id in 
the Source ID field, otherwise it will be found using the Resource Name field. 

bit 4: need not exist; if this bit is 1 then the resource need not exist on the source disk. If the 
resource does not exist then the resource atom will be ignored. 

bit 5: even if protected; if this bit is 1 then the resource will be deleted from the target file even if it 


is protected in the target file. 

bits 6-15: reserved; should be specified as 0 

bits 16-22: Currently these flags are only used when specifying a FOND resource and should be 0 for 
any other type of resource atom. They are used to specify which styles need to be included. 
*** Bruce- explain this. 

bits 23-27: reserved; should be specified as 0 

bit 28: deferred delete; if this bit is 1 and the user clicks Install then the resource in the target file 
will be deleted after the file copies take place. This allows copying entire files and pruning 
them down rather than having to copy a file resource by resource just to exclude a few re- 
sources. The resource specified need not exist in any source file (Just specify a source file 


spec id of 0). 

bit 29: copy; if this bit is 1 and rie user clicks Install then me resource in the source file will be 
copied to the,targe e-file if need not exist (bit 3) is 
0. 

bit 30: delete on insfall; jf his bit is 1a g pxists-in-the target file and the user clicks 
Install then t € (before the resource is copied 
from the sougce et file then this bit will be 
ignored 

bit 31: delete on re ¢ i he resource eXists infthe target file and the user clicks 


Boot Block Atoms 


Boot block atoms are used to write or change the parameters in a target volume’s boot blocks. Boot 
block atoms are different from file and resource atoms. They can indicate something to be copied or in- 
dicate an individual parameter that needs to be changed. 


To cause boot blocks to be written to a target volume, include a Boot Block Atom with a key of type 
‘bbUpdate.’ The parameto this type of Boot Block Atom is an integer which indicates the ID of a file- 
spec in the script. The file indicated by this file-spec should contain a ‘boot’ resource. A copy of the re- 
source is written to the first two blocks of the target volume. 


The format of a Boot Block Atom is shown in the following figure. It contains five fields. 
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Boot Block Atom 


Boot Block Atom Format Version (2) 
Boot Block Atom Flags (2) 


Boot Block Value Key (2) 
Boot Block Value | variable 
Boot Block Atom Description (pstr) 


Figure 9. Boot Block Atom 


Boot Block Atom Format Version 

The Boot Block Atom Format Version field (2 bytes) is an unsigned integer indicating the version of 
the boot block atom format. It is currently 0. If the Installer encounters a Boot Block Atom Format with 
a higher version number than it currently knows how to handle, the atom will be ignored. 


Boot Block Atom Flags 
The boot block atom flags fletermine when the gtom shpuld be used. 
flags, with only the two lowest pits currently being pised. 


Boot Block Flags {flow word 


tis a wowd consisting of 16 bit 


2AOUaI UO asuRYd 


Figure 10. Boot Block Flags (low word) 

bit O: change on remove; if this bit is 1 then the change will only happen if Remove (option-Install) 
was clicked. 

bit 1: change on Install ; if this bit is 1 then the change will be made if Install was clicked 


bit 2-15: | reserved; should be specified as 0. 


Boot Block Value Key 
The Boot Block Value key field is a 2 byte field that specifies which boot block parameter is 
being given a value in the Boot Block Value field. The key can correspond to any of the parame- 
ters which are changeable in the boot blocks. The possible keys for this field are: 


-1 Copy over boot blocks from a ‘boot’ resource found in the file whose file spec ID is given in 
the value field (word). 
1 The value in the Boot Block Value field updates the boot blocks ID (word) 
2 The value updates the boot block entrypoint (long) 
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3 The value updates the boot block version (word) 
4 The value updates the page 2 usage flags (word) 
5 The value updates the name of the system resource file (string) 
6 The value updates the name of the system shell (string) 
7 The value updates the first loaded debugger’s name (string) 
8 The value updates the second loaded debugger’s name (string) 
9 The value updates the file name of the startup screen (string) 
10 The value updates the file name of the startup program (string) 
11 The value updates the file name of the system scrap file (string) 
12 The value updates the number of FCBs to open (word) 
13 The value updates the size of the event queue (word) 
14 This boot block field is no longer used 
15 This boot block field is no longer used 
16 +‘ The value updates the size of the system heap on a512K Mac (long) 
17 The value updates the absolute size of the system heap (long) 
18 Thie boot block field is not longer used 
19 The value updates the minimal additional system heap space required (long) 
The value updates the the fraction of memory available to be used for the system heap (long) 
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Network Installation 


We are receiving feedback from customers that the ability to Install system software over the net- 
work is very important. Ideally we would like allow people using the Installer to update the system they 
are currently running on. This is not a simple proposition. It is much simpler to update a non-boot disk. 
At the very least, Installer 3.0 will allow non-boot disks to be installed on and updated from an 
AppleShare server. The Installer, scripts, and all of the necessary files will all be able to be placed on a 
server. This way if someone mounts an AppleShare volume, they will be able to run the Installer from | 
the server and update any non-boot disks. 

If we have time (or possibly for version 3.1) we would like to implement the ideal, and allow the 
boot system to be updated. We propose doing this in the following way: 


1) Make a copy any files we will update. 

2) Move the originals into a well-known folder off of the root of the volume. 

3) Update the new copies as we normally would. 

4) Install an init which will remove the well-known folder and its contents at boot time. 
5) When we are done installing, force theuser to reboot when quiting. 


Thre are several problems 


ith this supped Ajmong them are, what 7 we are running under 
MultiFinder and other applicat i ake 


ers is worth the effort. 


Software Guts Descriptioy 


Installer. Since this is a very real possibility, we are structuring the code so that it is more modular and 
therefore more easily modifiable. The most obvious and highest level change lies in separating the user 
interface from the "guts" (grunt work) of the Installer. But each of these areas can be further broken 
down into potentially useful modules. The "guts" part is being broken down into pieces including 
modules for package handling, atom handling, Install/Remove, and default map processing. The user 
interface portion is broken into modules handling the various screens. Routines that all of these modules 
need are factored out into a library utilities module. 


See the interface sections of each of the code units for more detailed information about each of the 
modules. 


Localization Issues 


Splash Screen 

As mentioned before, the Installer’s splash screen is stored as a PICT that can be changed/edited by 
any scriptwriter or localizer. The Installer will look first for a PICT resource for the splash screen in the 
Installer script but if none is found it will then look for a text resource that it will display instead; this ac- 
commodates those countries where no facilities exist for editing/creating PICTs without downgrading 
the US version. It seems a shame that on a graphics computer like the Macintosh, we can’t assume that 
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facilities will be available to manipulate and localize graphics. But this is what we currently have to live 
with. *** Exact descriptions later . *** 


Help 

We will provide same capability for the help text that we are providing for the Splash Screen. First 
attempt will be to find a PICT (which allows for us to store styled text) in the application resource file 
and if that fails it will look for plain text resources. *** Exact descriptions later . *** 
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Open Issues = 


Here's a list of some of the issues and enhancement ideas that have not made it into this version of 
the Installer, but should be considered when writing future versions. 


¢ Network options 
¢ Backup of system files that we can go back to if an error is encountered mid-way into the installation. 


* The creation of a log resource that has a detailed description of what happened in the install (what files 
and resources were copied, replaced, deleted, etc. and what boot block parameters were changed). 
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ABOUT THIS DOCUMENT 


This is the Friday, January 13, 1989 version of this document. 


The purpose of this document is to describe the important differences 
between the interfaces of the current Finder (hereafter called the “old 
Finder”) and the Furnishings 2000 Finder (hereafter called the “new 
Finder”). Accordingly, many details of the interface that remain un- 
changed from the old Finder will be left unstated. In general, assume 
that the interface to the new Finder is the same as the interface to the old 
Finder except where stated in this document. 


The design is still in progress. Meanwhile, comments about the 
human interface are very eagerly solicited and should be directed (via 
the media of your choice) to: 


John Sullivan 
MS: 27-A 


VAX email: sullivan 


arked with asterisks 
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FINDER EXTENSIONS 


The new Finder is constructed in a modular fashion, so that users can 
configure their Finders to meet their needs. For instance, users who are 
using floppy drives may want to keep the Finder as small as possible, 
whereas power users with hard disks may want to include as many fea- 
tures as possible, possibly including homegrown features. Non-essen- 
tial, removable pieces of Finder functionality are called Finder 
Extensions. 


It is not yet certain which components of the Finder will appear as ex- 


tensions to the user. Preferences and Mover are two candidates (more 
on these later). 
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CLASSES OF FINDER OBJECTS 


There are five classes of objects in the new Finder. 


e Applications—the tools that provide the eapaPiine that users 
buy computers to use. 


¢ Documents—the files that are created by Applications to store the 
user's data. 


¢ Containers—objects for storing other Finder objects inside. 
e¢ Desktop Services—“applications” that perform actions on Finder 


objects which are dropped into them (as though they were 
Containers). 


However, each ic 
each class. 
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APPLICATIONS eS 


Applications are the class of objects having the characteristic in common 
that they open to provide access to environments tailored to provide 
specific functionality or mechanisms for the presentation of data. The 
class of Applications has been expanded to include other things that 
will be changed to behave like Applications such as DAs, cdevs (now 
called “Panels” or “Control Panels”), and perhaps some Finder 
Extensions. 


All Application icons will be based on the standard application icon 
graphic of a hand with a stylus writing on a diamond. 


DAs 

In the new erie Desk cessor directly from 
their icbns pplicgtions-tra ew Finder pro- 
vides almethanjsm_for users to put y icdore Dogiiments, and even 
Container enu where they cg be pened directly at 
any tine. T g longer have uy Yehavior, and there is 
no longer ghy reasoh for developers to cregte ne 


Panels are the-imeividtial components Of ontrol Panel DA, each of 
which provides a mechanism to seta related class of Finder and System 
parameters. Each Panel will have an Application-like icon and will 
open to a window containing the controls that are currently found in 
the Control Panel. 


The Control Panel DA could cease to exist but will not in order to 
maintain compatibility with the old Finder. It will continue to work as 
it does today; Panels in the System Folder will appear in the Control 
Panel DA when it is opened. 
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DOCUMENTS a 


Documents have not changed from the old Finder. They are the reposi- 
tories of the user’s data developed inside of Applications. 


Documents are represented by icons based on a piece of paper with 
the top right corner folded over. 
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STATIONERY 


The new Finder borrows from Lisa the concept of Stationery. Stationery 
objects are a special class of Document objects. The only difference be- 
tween a Stationery Document and an ordinary Document is that open- 
ing a Stationery Document does not open a window presenting the con- 
tents of the Stationery Document; instead, opening a Stationery 
Document creates a new Document with the same contents as the 
Stationery Document, and then opens a window presenting the contents 
of the new Document. Thus, opening a Stationery Document is like du- 
plicating a Document object and then opening the copy. 


Any Document can be turned into Stationery by selecting the 
Document and then choosing “Make Stationery” from the File menu. 
Turning a Document into Stationery appends “Stationery” to the 
object’s original name. 
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CONTAINERS i 


The Desktop, Disks, Folders, and the Trash Can are all members of the 
class of Containers. The distinguishing characteristic of all Containers is 
that they are used to store Finder icons in an inactive manner; dropping 
objects into a Container or opening a Container does not result in any 
action taken on the contents. 


Because the set of objects herein defined as Containers were 
originally designed as unrelated iconic objects, Container icons 
currently have no common graphic elements that are consistent across 
them all. It would very much improve the recognizability of Containers 
if a common graphical element could be superimposed upon the 
existing icons. Since there a are already icons for the Containers one wey 
to distinguish themes ry 
a perspective di 


noticing the co 
Containers. 


Disks : 


Disks in the Finder are a representation of any physical storage media 
that contain computer-readable information. Not all such media are ac- 
tually disks in the physical sense; this category also includes other 
media such as tapes. Disks are represented on the Desktop by an icon 
that shows the physical media of the Disk. 


Folders 


Folders are the only Containers that users create. Their purpose is to 
enable users to organize their Finder icons in whatever manner is most 
convenient for them. 


Folders have an established visual identity—a tabbed file folder. The 
basic appearance should be preserved but should be modified to have a 
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3D quality by representing the folder as an oblique view. 


Trash 


In the new Finder, the Trash is emptied only when the user selects 
the “Empty Trash...” menu item. The confirmation alerts that users 
currently get when they put Applications or System Files in the Trash 
are replaced in the new Finder by a single confirmation alert when the 
menu item “Empty Trash...” is selected. 


There are 1? items in the Trash for a total of 917K. 
A There are 5 Applications in the Trash. 
There are 2 System Files in the Trash. 


2B Trash will remove these forever. Are 


There are 8 items selected for a total of 375K. 
There are 3 Applications selected. 
There is 1 System File selected. 


Deleting the selection will remove these forever. 
Are you sure you want to do this? 


Delete Selection] {[ Cancel | 


(rough draft) 


The Finder’s Preferences includes a way to disable these confirmation 
alerts, for the power user who knows when he/she wants to throw 
things away. When the alerts are disabled, the menu item changes from 
“Empty Trash...” (or “Delete Selection...”) to “Empty Trash” (or 
“Delete Selection”). 
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Without automatic emptying, the Trash in the new Finder behaves 
more like a Folder than it does in the old Finder. However, it still re- 
tains some of the behavior that distinguishes it from a Folder, including: 


¢ Users may put multiple objects with the same name into the Trash. 
¢ Applications in the Trash cannot be opened. 
¢ Documents in the Trash cannot be opened. - 


¢ The “Put Away” menu item may be used to move objects from the 
Trash back to their previous location. 


Without automatic emptying, users have to be more aware of the 
state of the Trash. This is eased as much as possible in the new Finder 
by reminders that there are objects in the Trash when disk full problems 
occur. 


When the Trash or a Folder in the Trash is opened, the appearance of 
the resulting window should differ from non-Trash windows. 
Otherwise, users may be surprised by unexpected behavior (icons put 
up alerts instead of opening, “Empty Trash...” menu item gone, etc.). 
*** We need to find an attractive way to do this. Here is an unattrac- 
tive way: 
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CCU Levitz NNN 


22 items 97,426K in disk 2,371K available 


folder of doom 


Word 3.02 


Another possibility is to choose a different appearance for all icons in 
the trash, perhaps the /eff-line” style or the “bar-through” style: 


a =a 
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folder of doom 
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DESKTOP SERVICES 


Desktop Services are an independent class of objects that are a cross 
between Applications and Containers. They accept objects dropped on 
them and then carry out some action on those objects. Containers 
perform no actions on the objects inside them and so can be opened to 
remove the objects inside—a Desktop Service has an active and less 
predictable consequence on the objects dropped on them than simple 
containment. 


Desktop Services are essentially a graphical way of representing 
verbs in the new Finder. As such, they should be used instead of 
Applications only when the behavior they represent makes sense as a 
single-function Finder verb rather than as an environment. Electronic 
mail, backup devices, fax machines, and printers are all examples of 
facilities that seem to work well as Desktop Services (“send”, “backup”, 

yre-associated verbs). 


can be diopped on ea This can be done as it is for Containers, . 
giving them an oblique view. 


(these are ugly) 
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SOFAS 


Definition 

Every file (including Applications, Containers, and Documents) is made 
up of three elements—an icon, a name, and the data in the file itself. 
Users see only the icon and name in the Finder. To see a representation 
of the data in the file, the user must open the icon. 


A Sofa is a special, new kind of Finder object that is a copy of a file's 
icon, a copy of that file's name (initially), and a pointer to (but not a 
copy of) that file's data. Only one instance of the data in a given file 
exists, but any number of Sofas for that one file can be created. 


Design Assumptions 


Copying). 


e All Finder objects can have Sofas made for them. This includes all 
Applications, Documents, Containers, and Desktop Services. 


¢ When a Sofa document is opened from the Finder, the Finder 
passes the target of the Sofa to the appropriate Application. 


¢ When a Sofa document is opened within an Application from 
Standard File, Standard File passes the target of the Sofa to the 
Application. 
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A Sofa gives the user a Finder object that they can manipulate 
independent of the object it points to but which opens to reveal the con- 
tents of the target object. 


Sofas are provided as a convenience for users. They provide a facility 
to fulfill the desire of many users to have multiple copies of individual 
files while maintaining the constraint that all the copies remain identical 
to each other when any one of them is modified. 


¢ Sofas would, for example, allow an Application (and all its 
ancillary files) to be located together in a Folder while allowing 
the user to keep an icon for the Application on the Desktop so it 
can be opened conveniently. 


¢ Multiple copies of files would allow users to find them easier in 
their Folder hierarchy just by virtue of the fact that there would be 
more copies of the sought-after object (as though you were 
pst-car keys in the house but there were three 
TOtse : ne). 


¢ Multiple copies of the Trash Can would allow users to see that 
icon in MultiFinder, for example, even though the Desktop was 
covered with open Documents and Folders. 


¢ A consequence of allowing Sofas to point across Disks and 
Networks is that users will be able to have (apparently) local 
copies of the latest versions of remote objects, without having to 
worry about updating their local copies. 


We have yet to decide upon the appropriate name for what we here call 
“Sofas”. The best solution would be a word for which the noun is the 
same as the verb (e.g., “a clone”, “to clone”). This would make the 
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menu items much easier to specify. Some possibilities are: 


possible unlikely 
Links Markers 
Tokens Alternates 
Fakes Surrogates 
Aliases Shadows 
Pointers Phantoms 
Substitutes Likenesses 
References Clones 
Stand-Ins Ghosts 

Virtual Objects 


they are Sede 
the consequences 


Furthermore, any visu ion nie Sofas in the Finder must work 
for icon views as well as text and small icon views. -Since text views 
show only a very small graphic it seems desirable that any visual 
distinction for Sofas should apply at least to the name, but not 
necessarily only to the name. Since Standard File presents a text view 
whatever visual representation chosen for Finder text views should be 
constrained to work for Standard File also. 


Visual Design for Sofas 


With the above discussion in mind, the visual representation suggest- 
ed for Sofas is to use the same icon as the target object and to add an 
outward-pointing triangle to the filename. The triangle character is not 
editable, although the name is. The triangle character can be thought to 
indicate a “pointer” to the real file and so hopefully will be less difficult 
to remember than a completely arbitrary symbol. 
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H & eo 4YoYoDyne <& 4A Very Long Nf... 
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Putting the triangle character at the end of the filename has the 
advantage that the first “real” characters of filenames in list views and 
Standard File are aligned. 


Sofas are created by selecting an object (or multiple objects) and 
choosing “Make Sofa” from the File menu. (A menu item name will be 
specified that is consistent with whatever we decide to name Sofas.) 
One Sofa for each selected object appears in the same Container with a 
variant of the original name (“Sofa of <object name>” with the triangle 
symbol added). 


If a Folder is selected when the “Make Sofa” menu item is chosen, a 
Sofa of the Folder is created but Sofas for the contents of the Folder are 
not created. This implies that part or all of the file arin eee 
cannot be made into Sofas in ong ofa” 


This results in a deus y trdirect Sofa (a concept that many users may 
have difficulty with but which does provide significant value). 


An example of the usefulness of doubly indirect Sofas is for updating 
the Apple Phonelist stack. The Phonelist author could have a Sofa ona 
publicly accessible file server that points to the current version of the 
stack. Each user could have a Sofa that points to the Phonelist author’s 
Sofa on the file server. When the author wanted to update the stack 
they would only have to change what file their public Sofa pointed to. 
Each of the users with their own Sofa pointing to that public Sofa would 
not have to make any change to their local environment but would 
automatically have a Sofa pointing to the latest version of the stack. 


Opening a Sofa Application, Document, or Container opens the real 
Application, Document, or Container. When an Application or 
Container is open, all Sofas for that Application or Container will ap- 
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pear open as well. It would be nice to do this with Documents as well, 
but this is currently technically impossible. 


Dropping Onto Sofas 


Dropping a Finder object onto a Sofa Container or Desktop Service has 
the same effect as dropping the object onto the real Container or 
Desktop Service. 


Standard File 
Sofas are visually distinct in Finder text views and in Standard File. 
When an Application opens a Sofa from Standard File the effect is the 


same as opening a Sofa in the Finder (i.e., the object that the Sofa points 
to is opened). 


Copying and Duplicating 


When copied (by dragging to another Disk or by option-dragging 
within the same Disk) or duplicated (via the “Duplicate” menu item), 
Sofas act the same as any other Finder objects, except for the special case 
when a Sofa and its target object are copied at the same time. In this 
case, the new Sofa will point to the new target object. (If a Sofa is copied 
or duplicated without copying or duplicating its target object, it will 
continue to point to the same target object as before, even if across 
Disks.) 

Therefore, with Sofas, copying two objects at the same time is not 
necessarily the same as copying the two objects one ata time. This will 
probably cause some confusion for some people. Our hope is that in 
general this behavior is natural, so that most users will not even notice © 
it; the Finder will simply “do the right thing.” 
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Sofas can be renamed the same way and with the same restrictions as 
any other icon in the Finder, except that the triangle symbol cannot be 
edited. A consequence is that it will be possible for the user to forget 
what object the Sofa points to. The target object’s name will be dis- 
played in the Sofa’s Get Info box to help alleviate this problem. 


_ Going to the Target Object 


Clicking on a sofa’s arrow symbol opens a window containing the tar- 

get of the Sofa, scrolls so that the target is visible (if necessary), and se- 
lects the target. If the target cannot be found, the broken sofa alerts are 
used (see below under “Broken/Orphan Sofas”). 


In Standard File, clicking on a sofa’s arrow does the Standard File 
version of the same Bung: it ia the folder ces ue eet of 
the sofa, selects the i 
ble. 


Option-clicking on% : 
the window containing the Sofa. If the target is ona different disk, it 
copies the target rather than moving it. 


Note: This feature may prove to cause more problems than it solves, 
due to the copy/move distinction. It will be implemented and tested 
and (like all other features) if it turns out to be non-useful it will be 
junked. 


Since Sofas are visually distinguished we can assume that if the user 
drags one to the Trash Can that it is their intention to delete the Sofa 
and not the object it points to. If the user has the Sofa but wants to 
delete the target object then they need to use one of the command for 
finding the target object of a Sofa to get to the target object and then de- 
lete it. 
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There are several potential causes of broken (dangling?) Sofas (i.e., Sofas 
that point to nothing). 


One cause of broken Sofas is that a Sofa points to an object on a Disk 
that is no longer mounted. In this case, when the Sofa is opened the 
Finder will attempt to mount the needed Disk, either automatically (for 
connected but unmounted Disks, possibly for AppleShare Disks) or by 
asking for the unmounted Disk by name. For ejectable media, the exist- 
ing disk swap alert will be used (but with a Cancel button); for non- 
ejectable media, the following alert will be presented to the user: 


The target file "Sofa Target" is on 
the disk "Annulus". 


Please connect the disk "Ann 
ifavailafle)then try ggain. 


Sofa but in Somre-easeS it might (for instance; moving and renaming the 
target object will almost certainly break the Sofa if the target and Sofa 
are on different Disks and the Sofa’s Disk is not mounted). In addition, 
due to the imperfections of hardware and software there will always be 
the chance that a Sofa will become unexpectedly broken. When a Sofa is 
opened and the Finder cannot find the target object although the target 
Disk is mounted, the following alert box will be presented to the user: 


Couldn't find the target file 
"Sofa Target". 


If the file still exists, please 
make a new sofa for it. 
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Since the Finder (like most Applications) is idle a significant part of the 
time, there is an opportunity to have a background process that 
searches for Sofas and upon finding one confirms that the pointer is 
valid. If the Sofa is broken the target object can be searched for on all 
mounted Disks. The drawback is that this is not an instantaneous event 
and so the user might still try to open Sofas that are broken but can be 
restored by a search of the mounted Disks. In that case the user will 
have to wait while that search is preformed in the foreground. 


When the Finder finds a broken Sofa it should change the visual 
appearance of that Sofa to reflect its broken-ness. (One might suggest 
deleting it but automatically deleting previously-visible files, even use- 
less ones, is not in the Macintosh spirit of things.) 


mm YoYpDyne> €& A Very Long Nl.> 
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VIEWS 


Definition 


Views are ways to present the contents of a container. The new Finder 
allows the user to create new, custom views in addition to using the ex- 
isting views (known here as standard views). 


Design Assumptions 


¢ Views will be customizable in place, in a manner such that drag- 
ging icons, launching applications, etc. still work as normal. 


¢ The aspects of a view that are customizable are limited by the con- 
straints inherent in-tke first assumption above. 


ng only the information a userfares gbout allows the im- 
ent information to Ye seen morf quickfy. 


ation a ser cargs about conserves screen 


¢ Allowing users to mix and match icon sizes with additional textu- 
al information combines the quick visual recognition of icons with 
the preciseness of text /numbers. 


¢ Some information that was previously hard to get at (e.g. the com- 
ment in the Get Info box) can be made visible quickly. 


Show/Hide View Tools 

There is a new item in the View menu that toggles between “Show View 
Tools” and “Hide View Tools”. When “Show View Tools” is chosen 
from the menu, the view-customizing tools appear in a HyperCard-style 
floating windoid. In addition, clicking on a field of the selected icon 
puts a drag outline and grow handle around that field. Dragging from 
the drag outline moves just the chosen field with respect to the other 


components of that icon. Dragging the grow handle resizes the chosen 
field. 
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folder of doom 


(Peer sevocesecces: 


Selecting “Hide View Tools” returns the active window to its normal 
state and closes the view tools windoid. It is important to note that all 
normal Finder operations (dragging i icons, launching things, selecting, 
renaming, etc.) still work even when the view tools are visible. 


Since the standard views are not editable, when a standard-view win- 
dow is frontmost the tools in the view tools windoid are inactive, and 
no MacDraw-like handles appear. 


the new view, shee? ow View Tools” makes visible the tools for 
modifying the existing frontmost window’s view but does not create a 
new view. 


Deleting 
There will be a method to delete any custom view. This will remove the 
custom view from the menu and all directory windows that formerly 
used that view will instead use the standard view from which that view 

was derived. This action will be Undoable so that no confirmation alert 
is necessary. 


*** What is the method for deleting a custom view? Menu item? 
Button in the windoid? 


Modifying 
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When the view tools windoid is visible and active, the view in the front- 
most window can be modified. Any changes that are made to the view 
in the frontmost window become part of the definition of that view, and 
any other windows using that view will be appropriately updated (ei- 
ther in real-time as the view is being edited or when another window is 
made frontmost). 


The simplest of the several ways to modify the view is to rearrange 
and resize the visible information. As mentioned above, when exactly 
one object in the window is selected, clicking on a component of that 
object puts a drag outline and grow handle around that component. 
The grow handle is used to reshape/resize that component, analogous 
to the grow box in a window. Some items are constrained to a single 
line, whereas others (e.g. the comment) can be shaped arbitrarily. The 
icon when reshaped will snap to any of the defined icon sizes (there are 
currently three, but there may be more later). The drag outline is used 
to drag the component{so-g new position relative to the other fields of 


arg of central impor- 
ll other Zompgnents may be 
e available components are 
tool palette Dragging a component from 
pite{o an iconjinside the frontmogt direcfory window adds that 
comppnent fp the vigw. (Altgrnative: t4rning A component “on” via 
: | indoid adds that compo- 
“nent tO\he view.) Draggitig a component from the frontmost directory 
window tOthe-palettéremoves that comrporent from the view. 
(Alternatives: dragging a component out of the window removes it; 
dragging a component out of its icon’s bounding box removes it; turn- 
ing the component “off” somehow from the view tools windoid re- 
moves it.) 
***Still need to control: sort order; justification of text fields, layout 
of icons. (Font and fontsize? Or is this global for the Finder?)(relative 
positions of components?) 
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CONFIGURING THE APPLE MENU 


In the new Finder, users have control over what appears in the Apple 
menu by the use of a specially-designated Apple Menu Folder. Every 
icon in the Apple Menu Folder will appear in the Apple Menu. This 
happens instantly (not only at startup), so that if a user drags an icon 
into the Apple Menu Folder and then pulls down the Apple menu, that 
icon appears in the list. 


Selecting one of these items from the menu is equivalent to opening 
the icon. This is true regardless of what kind of icon it is (Container, 
- Document, Application, Sofa, Desktop Service, etc.). 


Desk Accessories in the System file will appear in this list as well. 
*** In the current version of the new Finder, the Apple Menu 


Folder is designated ls a biaea pnfin the System ee and name 
(“Apple Menu”) r-* 7 Use y ally 
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PREFERENCES 


Many aspects of the new Finder will be customizable. These include the 
Apple menu and Views, as described elsewhere. The interface to sever- 

al other customizable features will be bundled together under the name 

Preferences. 


*** It is undecided how the Preferences interface will be accessed. 
There may be a menu item, there may be a stand-alone openable icon 
(a la Panels), or the Finder file itself may open into the Preferences in- 
terface. 


A user's Preferences will be saved in a document so that they may 
easily be transferred from machine to machine. 


The list of things that can be set with Preferences has not been fully 
decided but may include: 


eh A 
cided alsv: 
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MOVER (—_} 


In the current arrangement, users must use a separate and somewhat 
mysterious application (Font/DA Mover) to move Font and DA re- 
sources in and out of the System file. Other resources can only be 
moved with ResEdit (not for the faint of heart) or specific third-party 


applications such as the Sound Mover. With the new Finder, users can — 


manipulate movable resources directly, in much the same way as they 
manipulate files and folders.. 3 

Mover is not an application; there is no double-clickable Mover icon. 
Instead, “Mover” is a term used for the new functionality of being able 
to directly manipulate fonts, DAs, etc. 


*** Tf Mover is implemented as a removable extension it may have an 
icon*** 


Opening the System File 


The System file in the new Finder isfopena ow 
displaying two kindgoftcors-imdividual ontéize, 
one DA, one sound), oHech of i ich far as 
suitcases. 


22 items “~~ \ 97,426 ic Hick OETA availabla Lf 


Wit 


a NO 
cl Aeiteme J o7928K nape 254K avatade | 
fe 


Alarm Clock Calculator - Monkey 


73 oO fF 


Helvetica Palatino Times 14 


The suitcases are very much like folders in most respects, except they 
can contain only Mover icons, including suitcases (if other icons are 
dragged into a suitcase, they will zoom back from whence they came). 
All Mover icons can be dragged back and forth between the System file 
and the Finder’s file hierarchy and they behave exactly the same in any 
location, with the exception of special properties that come from being 
in the System file (e.g., DAs show up in the Apple menu automatically, 
fonts show up in Font menus, sounds show up in the Sound panel). 


Note that although suitcases can be dragged back and forth from the 
System File to the Finder’s file hierarchy, this is not true of other 
Containers. Folders can not be dragged into the System file. Only 
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Mover icons can be put into the System file. 


When the user opens a System file that has never previously been 
opened, it will arrange the contents in some reasonable fashion, such as 
putting all sizes of a font together in a suitcase, and perhaps putting all 
font suitcases together in another suitcase. However, users are free to 
reorganize the Mover icons inside their System files in any way they 
want to, without affecting behavior. For example, a suitcase may con- 
tain a few sizes of Helvetica, a few sizes of Times, and some DAs. 


All Mover icons are openable. Opening a suitcase creates a window 
displaying its contents in just the way opening a Folder does. Opening 
a DA icon opens that DA just as if it were selected from the Apple 
menu. Opening a sound icon plays that sound, and then closes the icon. 
Opening a font icon probably displays a sample of that font in a win- 
dow. These behaviors geeyr whether the Mover icon is in the System 

eFirde erarchp 


ABCDEFGHIJKLMNOPQRSTUVWXY Zab 
cdefghijklmnopqrstuvwxyz1234567890!@#t 
$%*8&*()-_=+[{ }]):'",.<>/2a[ed’ fO*A°-p~ 
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HELP 


The software support underlying the help described here is intended, 
ultimately, to be included in the ROM as a Help Manager. Given that, 
help in the Finder will ultimately be implemented by making calls to 
that Help Manager. Meanwhile, help will be designed for and 
implemented in the Finder as an example to application developers of 
the way that help can be implemented in an application and to suggest 
to developers that help should be implemented consistently across all 
Macintosh applications. 


A focus on users’ help needs has led to a “modular” design for help, in 


which different types of help are provided to address different types of 
questions. 


Goal Help 


may also be incl 
“What can I do wi 


operating your comp’ 
se to organize : 
start other applications, You use the Finder every time 


you start your computer or whenever you move from - 
one application to another, 


Fieder: 6.0 Larry, Jeha, Steve, and Bruce 
System: 42 ©1987 Apple Competer, ine. 


Total Memery: 1 024K 


“What Is __?” Help 


“What Is__?” help allows users to click on objects or menu items in 
the Finder to get a short piece of descriptive information. The 
information will appear in “bubbles” next to the objects and menu 
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Folder 
Contains documents, 
applications, or 

other folders. 


items. 


There are two ways to access this help information. The first is 
designed for new users who are using help to explore the Finder 
environment. Access is readily apparent through a menu titled “?” in 
the menu bar. The user enters a “help mode” by choosing the “What Is 
__.?” item in the ? menu. While in this “WhatIs__?” mode, the cursor 
is a question mark and the appropriate help bubble appears whenever 
the user clicks on an object or drags through a menu item. To exit from 
the mode, the user toggyesghe menu item or hits an (as yet to be deter- 


included sq that-nrere-experiencédwsers can geyqui 
object or functiotwithout the overhgad ofSelecting a menu 
item twice (prfCe fONurn it or, once to turn ifoff). A 
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“How Do! ___?” help provides step-by-step instructions for common 
Finder tasks. When users choose “How DoI__?” from the ? menu, an 
access screen showing a list of tasks appears. Users can choose a task to 
see the related subtasks. The subtasks will appear to the right of the 
main tasks. Choosing a subtask causes the procedure for that subtask 
to appear. (Choosing a different main task causes a new list of subtasks 
to replace the previous list.) 


Changing window size 
Moving a window 
Making a window active 
Closing a window 
Using the scroll bars 


Manage documents 
Manage folders 

Manage applications 
Manage disks 


scoonsoQPPebbenatteteapotectensaccanstecberstaccaseceseosves 


users to search 2” dgtabase lik¢ a Thesprus by typing 
keywords. 


Changing window size 
The zoom box lets you use every 
1. Position the pointer on the size box square inch of the screen for what 
and dragitupand tothe left. i j you're currently working on and, 
(The window gets smaller.) is with single click, brings you back 


to your former view. 


2. Position the pointer on the zoom box 
and click. (The window zooms out.) 


Related Topics: 


3. Click the zoom box again. (The ¢ Size box 
window returns to its former size.) * Zoom box 
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Clicking the zoom box toggles between the two-page and one-page 
formats. (This allows users with small screens to see the help text and 
their application at the same time.) 


EME How Do |..? Sees 
Changing window size 


1. Position the pointer on the size box 
and dragitupandtotheleft. i j 


(The window gets smaller.) I 


2. Position the pointer on the zoom box 
and click. (The window zooms out.) 


3. Click the zoom box again. (The 
window returns to its former size.) 


mghu, they will 
the Finder, AltYough this kind of 
frequent use shofld hgfp new users 


help hasp game-like qualit 
become qxpeyUsers: 


from the Eg 
Misplayed to the right of the commands 
in the menus. 


Bookmark 
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CHOOSER 


Choosing external devices, particularly network devices, is very 
difficult using the Chooser today. A simple first step to improving the 
situation would be the implementation of permanent address objects 
that can be saved and reopened. This would mean that users would 
only have to use the Chooser once to gain access to each 
network/external service. After that initial connection the address 
object/icon would be saved (on the Desktop or in a Folder) to be 
reopened when needed. 


These address icons are Sofas; users create them using the “Make 
Sofa” menu item. Like other Sofas, these icons remain on the Disk even 
if the device or network connection is broken. The only way to make 
the icons disappear is to explicitly drag them to the Trash (and later 
empty the pant These icons are glways in one of three states: off-line 


The “off-line and closétform of the icon stores the device address. 
When it is opened the device is mounted, a window displaying the top- 
level contents of the device appears, and the icon changes to the “on- 
line and open” form. Closing this window changes the icon to the “on- 
line and closed” form. Unmounting the network device changes the 
icon to the “off-line and closed” form. 


p- 33 Friday, January 13, 1989 


Finder HIS 


STANDARD FILE 


Although the MultiFinder environment makes Standard File less impor- 
tant than it has been in the past, the day is not yet here when it will go 
away entirely. Therefore, it should be kept up to date with changes in 
the Finder, and remaining flaws in its design should be fixed where this 
does not introduce major incompatibilities or user confusion. 


There are four changes to Standard File: 


¢ An additional, topmost, level in the hierarchy (the Desktop) has 
been added 


° The “Drive” button has been changed to a “Desktop” button 


¢ The Trash is visiblelike any other container. 


¢ Sofas are supported. 


In the did g ippmost (or bgttommmost, if you’re 
sk/vofume level. To get from 
disk tf disk,¥he userjclicked pn the Driye buttgn. This is an inefficient 
no way to tell how many disks 
rough ayd there is choose a particular disk. 


gets worse and worse. 


In the new Standard File, the topmost level in the hierarchy is the 
Desktop level. This is analogous to the way the Finder presents the file 
system hierarchy. At the Desktop level are all mounted volumes (which 
appear on the desktop in the Finder), along with any files that the user 
has stored on the desktop. Therefore, in the new Standard File, the user 
can see at a glance all of the available disks, and choose the one he/she 
wants ina single click. 


Also visible at the Desktop level is the Trash (more on this below). 
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<> Mojo 


@& MPW 3.0a2> 
Skid 

WU Trash 

QO Valuable Secrets 
D UAH Mail 


need for a buttonjthat cycles throug them {compulsive mouse-hatprs 
can still use the pb o.cycle through dyives Desktep bytton 


just like any oth ith the exceptiony that itqms in the Trash 
cannot be opened (frer j i -aaKe 
(from PutFile). Even ough the Trash in the new Finder i is similar in 
many ways to an ordinary Folder, we want to reinforce the idea that it is 
in fact a repository of unwanted items and not just another Folder. This 
is to prevent people from accidentally deleting important files. 


© Bye-Bye Folder Trash 
i] Hejected 


 Unieved 


on 


ii Umpanted Desktop 
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Sofas in Standard File behave analogously to Sofas in the new Finder. 
When a Sofa is opened, the target of the Sofa is opened. Thus, opening 
the Sofa for a Container will display the contents of the target 
Container, and opening the Sofa for a Document will return (to the ap- 
plication) the name and path of the target Document. Also, as in the 
Finder, clicking on the arrow symbol of a Sofa will display the contents 
of the Container containing the target of the sofa, and highlight the tar- 
get. 
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QUICK FIND 


Quick Find is a mechanism to quickly locate an individual Finder 
Object. It is as simple as possible to solve the 80% of the cases in which 
a user wants to quickly locate a file. Selecting the menu item “Find...” 
from the Edit menu brings up the following dialog: 


g “Finc 
fsers can quickly ge 


The last window opened (not merely brought to the front) with 
“Find...” or “Find Next” will be closed the next time either of the Find 
commands must open a window. 


An outstanding problem is that of objects found on the desktop, which 
can obviously not be brought to the front. Two potential solutions are: 
(1) make the Find dialog a modeless window with some space for a 
message. When an object on the desktop is found, the message “<file 
name> found on desktop” appears in the window; (2) put up an alert 
saying “<file name> found on desktop”. Quick Find must be imple- 
mented in both of these ways to determine which is better. 
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MOUNTING & UNMOUNTING 


Fear of erasure has prevented many a user from dragging their device 
icons to the trash in order to unmount devices. However, many other 
users are quite happy with doing so, especially since it is so quick and 
direct. We need to provide an alternate way to unmount devices, with- 
out discontinuing the trash method. 


The obvious and simple but not completely elegant solution is to add 
an “Unmount” menu item to the Special menu. When this item is se- 
lected, the Finder attempts to unmount all selected disks, or the disk 
owning the frontmost window if no disk icons are explicitly selected. 
Of course, disks with busy files cannot be unmounted, just as today. 


ooks for di- 
ts their icons 


*** A imoget ution would be nicerout We need something 
ethi g bett¢r? One other possi- 
e “Py¥t Away” menu item 


of investigation is\pverloading 


to unmount when digks are selected. 
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MENUS é File Edit 2 Wiew Special Color 


About the Finder... 
Set Aside Finder 


[Other Entries] 


About the Finder... 


This item will i ind ude the standard Applica ion igendincavon along 


Apple Menu. 
[Open Objects] 


Each Application that the user opens will be listed in this section of the 
Apple menu. 


[Other Entries] 
The user controls which Applications, Containers, Sofas, and 
Documents are in this menu by putting icons in a specially designated 


Folder. Selecting an item from this menu is equivalent to opening the 
associated icon. 
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File Menu 


New Folder 
Open 360 
Print 

Close Window 
Get Privileges 
Get Info 36 I 
Duplicate 36D 
Make Sofa 

Make Stationery 
Put Away 


Posenvccncencaccssesecousesercesccecesccoocoveecuesvesecoceeneceece. 


p$e to more accurately 
ojclose open applications. 


Make Sofa 


If one or more objects are selected then this menu item will be enabled 
and, if chosen, will create a Sofa of selected object or objects. 


Make Stationery 


If one or more Documents are selected then this menu item will be en- 
abled and, if chosen, will turn the selected Documents into Stationery 
Documents. 


Put Away 


This item continues to work as it did in the old Finder. When it is cho- . 
sen, selected items on the desktop or in the Trash are moved to their 
previous non-desktop and non-Trash locations. With the changes in the 
Trash, it may be more commonly used than it was previously. 
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Print Window... 


This menu item has been changed from Print Directory... for clarity. 
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Edit Menu 


oe veesccasesececssccvesecsecesccuccscconavscsecesessoessosemes. 


Cut Text 
Copy Text aC 
Paste Text sU 
Clear Text 

Select All 


Peercccccccccccscceccooccesssncenscceesosconssesceseeseoooowes 


Poeseveccecoceccseveosecoccesescoseceeseceeveccccceseseescemcs 


Find intakes the Quick Eietd sane box, and s¢arches all mounted Disks 
(see Quick | 


Find Next 


Find Next searches for the next occurrence of the text last specified in 
the Quick Find dialog box (see Quick Find section above). 
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About the Finder... 


What is __7 
| How Do | __ 
Did You Know __? 


The placement of this menu is still being debated by the people who are 
writing the Help Manager for the toolbox. It may end up after the Edit 
menu, before the File menu, or after all the other menus. If you are con- 
cerned with influencing this coy contact Kate Gomoll (x3562) or 
James Sulzen (x3142). 


See the Help sect} 
these menu items 


out 
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View Menu 


By Small Icon 
By Icon 
By Name 
By Date 
By Size 
By Kind 
By Color 
New View 
Show View Tools 


cnn esessacascscecesscscccrencoccvcccscesccascscccssescaceseecccsosconsesecs 


menu item text c ane to “Hide View Tools.” 4 Selecting “1 “Hide View 
Tools” makes the view-customizing tools and controls invisible, and 
changes the text back to “Show View Tools.” 


By Custom Views 
This section automatically includes any views created with the New 


View menu item, as well as any views moved into the Finder with the 
Mover. 


. Friday, January 13, 1989 p.44 


Special 


Clean Up 
Empty Trash... 
Erase Disk... 
Set Startup... 


Mount All 
Unmount 


Restart 
Shutdown 


Empty Trash... 


when the frontmost window is in ER Trash. | 


Erase Disk... 


This menu item\incorperatesf£he funcfonality offthe apylication “HD 
Setup,” so that initializing hard di barent ab initializing 
floppies. 


Mount All 
When the user selects this item, the Finder checks for directly attached 


_ Disks that are unmounted, and mounts any it finds (so their icons show 
up on the desktop). 


Unmount’ 


When the user selects this item, the Finder attempts to unmount any se- 
lected volumes. Ooviously; selected volumes with busy files cannot be 
unmounted. 
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Color Menu 


Prototypes have been built in the Human Interface Group exploring the 
use of color to display Finder information such as age or size of a Finder 
object. The Finder group does not plan to include any of the results of 
this work in the new Finder. For additional information about this 
work, n (x4- 
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furnishings 


External 
Reference 
Specification 


About This Dog 


This document, and the ots : 

Finder. Furnishings 2000 Humarrtnrerface Specification S many new Finder features from an 

user’s point of view, while this document addresses some issues for applications and system software. 
Other documents that have been used in the design of the Furnishings 2000 version of Finder include 

NewNewFinder and Extensions: External Reference Specification, an earlier ERS, and NewFinder and 

Extensions: External Reference Specification, an even earlier one. 


In addition there are a number of HyperCard prototypes for various features of Furnishings 2000. 
These can be found on the “Finder++” AppleShare server in the “Gasséeville” zone. 


Comments to Darin Adler, MS: 27-AJ, x4-3621, AppleLink: Adler4. 
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Why a New Finder? 


There are three basic reasons why we are rewriting the Finder, and implementing new features: 


Simplification and Consistency 
Stability and Ease of Modification 
Competitive Advantage 


Simplification and Consistency 
The most important aspect of the project is improving the Macintosh experience by increasing the consis- 
tency of the Macintosh interface (more use of the desktop). 

The Finder provides a way to manipulate files and start applications. Macintosh users generally like its 
intuitive feel, but much of the rest of our software does not have this kind of interface. Files and folders 
are manipulated directly, but fonts and desk accessories are manipulated via lists in a modal application 
(“Font/DA Mover”), and system preferences are set with a desk accessory (“Control Panel”). With this 
Finder, more system utility functions (choosing printers, installing new software) use a direct manipula- 
tion interface. We also make it easier for applications to have a Finder-like interface by making Finder 
code accessible. 

In today’s Finder, applications and documents can be opened by menu item or double-click. 
Unfortunately, many other objects-th 
the user can see cannot be ope 
Currently, you get the following 
when you try to open the “Gene 
panel: 


This is changed so that panels a 


ase of Modification (Extensibility) 
The old Finder was written in assembler and C. It is difficult to 


Rate of Insertion. 


=== 


| nnn Slow Fast 


Time O 
1:48:52 AM 


Date 


Point Blinking make major changes to the existing Finder. The new Finder is 
fs written from scratch in C++. 
Desktop Pattern O8@0 We are also-creating an extension mechanism. This allows us 


to create removable feature sets for the Finder. These share much 
of the Finder’s code, but do not require a new version of the 
Finder. 


Competitive Advantage 

The Finder is the cornerstone of the Macintosh interface. 
Furnishings 2000 attempts to consolidate our advantage and ex- 
perience with direct manipulation, not by adding flashy new fea- 
tures, but by refining existing concepts, enhancing ease of use 
through simplification and consistency, and introducing a limited 
set of new concepts. 


O-NW SUH 
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Configuration 


The new Finder works on any Macintosh with at least IMB of memory and Mac Plus or newer ROMs. 
The main target machine is a 1MB SE with a hard disk. This is the machine that we will do most perfor- 
mance testing and tuning on. 

The new Finder requires a new MultiFinder. In particular, the enhanced desk accessory support is 
closely tied with MultiFinder, and some features that were formerly implemented with desk accessories 
(Control Panel, Chooser) will be done in the Finder. 


Memory Strategy 


In addition to using fixed heap space for the Finder data structures, we use system heap memory and 
MultiFinder temporary memory. This means that the Finder partition size is small, but that more memory 
_is used if many windows are open with lots of items in them. The key strategy here is graceful degrada- 
tion. If there is less memory, the Finder will do the same things, but more slowly. 


Names 


An international script number is stored wit 
ate font to display a foreign file name in. So 
specify the script for a filq while renaming it 


gach file and folder. This allows us to choose an appropri- 
eone uping the Finder in a multiple script environment can 
by swit¢hing keyboard scripts. 


Icons 


In addition to the 32x32 idgnYwe currdantly support, we are agding sApport for hand-tuned 16x16 icons 


Trash 


The trash is implemented as a directory on each volume, and emptied less often. Note that this means 
that applications can move files into the trash. In addition, trash on MFS volumes is always emptied right 
after you drag a file in and an ominous dialog appears (because there are no directories on MIS vol- 
umes). In the old Finder, the trash is emptied at various times automatically. The new trash is only emp- 
tied when Empty Trash is chosen from the Special menu. 


Desktop 


The desktop is implemented as a directory on each volume. This allows applications to move files to the 
desktop. In addition, Standard File will be modified to recognize the Desktop, and to display files in the 
same hierarchy as on the disk. 
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Menus 


The Apple menu is user-configurable. Any Finder objects in the “Apple Menu Folder” will appear in the 
menu, and they are opened when the menu item is selected. This includes desk accessories, applications, 
documents, folders, etc. Note that this feature works particularly well when combined with sofas (see 
below). 


Clipboard 


The Finder will remain the standard place to display the clipboard. Our clipboard display will support 
‘PICT’, ‘TEXT’, and ‘styl’ (styled TextEdit) data from the clipboard. 


Disk Format 


The old Finder maintains specific additional information about the files on each volume. This is kept in a 
resource file for HFS and MFS volumes, and is maintained by a special call set for AppleShare volumes. 
The old Finder uses the resource file (named “Desktop”) to hold three things (note that the name has . 
nothing to do with the gray desktop of the Macintosh): 


Icon Database 
“Get Info” Comment Databas¢ 
Application List 


The icon database associates icon 
“Get Info” window. The application fokd€r Cache allows a quick looky by ¢eator of an application’s 
location on disk (for launching). | 

The icon database contains “bane which have beéen extracte4 tiles with the bundle bit set. 


make searches for Fant ete Gir re hetes document is dotbte ed) fast. 

All three of these are maintained by the old Finder. AppleShare introduced a new call set that re- 
placed these three “databases” for some volumes (those that respond to these new AppleShare Desktop 
calls). T here is a “workstation” implementation of this that is used to communicate with a remote server, 
and a “server” implementation that is used by AppleShare servers. 

The new Finder uses this call set for all volumes. In addition, some of this information will be main- 
tained by the file system automatically. The old Finder reads bundles out of files and enters them into the 
icon database, links files to their entries in the comment database, and maintains the application list as it 
moves applications from folder to folder. Some of these (at least the application list) can be better han- 
dled by the file system directly. 

The new Finder will also be written so that disks without desktop information can be used. Thus we 
will support locked disks without “desktop database” information. 
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Keyboard 


The new Finder makes more extensive use of the keyboard. When not renaming a file, the arrow keys 
and name keys can be used as in the Standard File package, to navigate between folders. These include 
the following: 


AITOW S: csculanceci pebacsces beasts move selection (through rows and columns of icons) 
Command-Up Arrow ........ open parent folder (and close current folder) 
Command-Down Arrow ...open selected folder (and close current folder) 
Other Keys ...........008 Seek typed name (as in Standard File today) 

Return or Enter... eee open file name for editing 


Note that use of these keys is never necessary. If you click on a file, you will still be able to edit it’s 
name, just as in the old Finder. 


Privileges 


Currently the Finder supports setting privileges for volumes with privileges (AppleShare). We will extend 
this feature by allowing setting of default peeideges for new folders. In addition, we will change the 


When this preference is activé}-ws om click and hold ® E 

window, a menu appears similar to the one in Standard File, allowing you to select any parent ae 
Note that even with this option active, you can still drag the window, if you click in the striped part of 
the title bar, or if you start dragging immediately. 


Full Path In Window Title 


When this preference is active, instead of displaying the name of a folder, a full path leading to the folder 
is displayed. 
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Views 


Much of the customization of the new Finder is accomplished with “custom views”. These are settings for 
the appearance of objects in Finder windows, similar to items currently in Finder’s “View” menu. 

Each view includes information about what is displayed for each object and how objects are ar- 
ranged. There two distinct kinds of views: “free-form” icon views and “list” views. The list views are orga- 
nized top to bottom, and the free-form views are organized left to right, top to bottom on an imaginary 
grid. 

In the current Finder, using a list view also implies using some kind of sorting. In the new Finder, the 
choice of sorting is separate from the type of view. In addition, any view (even a free-form one) can be 
set so that it remains sorted (and “cleaned-up”) all the time, like today’s “by Name”, “by Date”, etc. The 
“Clean Up” menu item sorts and cleans up the active window, so that any window can have sorting asso- 
ciated with it, even if it is not always sorted. 


View Editing 


© TFolder 


eae Last Modification . To create a custom view, the : New 
View” and “Show View Tools” menu 
items are used. When view tools (for- 
y rulers) ate visible, each element 


[) Barcolounger 

(2 Dresser 

(9 Midnight O71 Wed, Jan 
Sat, Dec 


(7) NowFinder 
(J OldFinder code 


: system with a slightly customized 
I gitems \X._4,6f8K available | ¥ (by Version) that shows the ver- 
————SE forr number under the file name for 
MouseDown changes all objects in the system folder. Of 
4K course, this view, once created, can 
Thu, Dee 8, 1988, 11:39 PM be ri for any other windows as 
well. 


Constant changes 
1K 


Wed, Dec 21, 1988, 3:06 PM 


App list changes 
1K 
Mon, Dec 19, 1988, 4:30 PM 
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Sofas 


Sofas are Furnishing 2000’s flavor of references between Finder objects. These are a special class of ob- 
ject, represented as file of type ‘sofa’ and creator ‘ZSYS’ containing information about the object refer- 
enced. We will define a file format that allows references for Finder objects. Specifically, to represent a 
file, we store volume and file information. 


Volume information includes: 


local volumes: volume name 
volume creation date 


network volumes: zone name 


server name 

user name (for server log-on) 
optional password (for server log-on) 
volume name 


File information includes: 


cNodeID 
file name 


To find a file referenced | : eNirst try tp find the volufhe (mpunt if it is a network volume), then 
look for the file, first by cNoa elD, ‘and dirID and fil e€ may introduce more information 
to allow sofas to remain P built” G.e., All dirl bs and cNodeID change). We refresh a 
sofa whenever we use itt Thi at the cpodelD, filé name/fdirID, etc. are stored again, giving the 


The sofa mechanism iSNmplemented s Keely fromfthe Finder itself. This allows other applications 
(and system software) to use thé sofa-following heuristics as well as the sofa data structures for any file 
linking they find necessary. For example, Microsoft could use them to improve Excel’s inter-spreadsheet 
linking. This mechanism is in the form of a set of calls which manipulate sofa handles which are normally 
stored in ‘sofa’ resources. Any file can have ‘sofa’ resources in it, which would automatically be “fresh- 
ened” by the Finder when the file was moved, copied, etc. This “sofa manager” scheme is currently under 
development in cooperation with the Diet Coke team, one of its clients. 
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Searching 


We are implementing two features to allow the user to search for files on disk. Note that this is the first 
time the Finder will live up to its name; we currently have a Finder that doesn’t know how to find! 


Find 


One type of searching is a quick find feature similar to the “Find File” desk accessory. There are two 
menu items for this: “Find...” and “Find Again”. The Find dialog will allow you to specify a string to 
search for. . 

Better performance for this feature is possible with file system support (the SearchVol call). Direct 
reading of the catalog file is much quicker than the GetCatInfo calls that the Finder would otherwise have 
to make. In addition, searching a server volume is much faster if the server does a search. 


Matching 
Searching with more complicated criteria is possible with the view mechanism (see section on views). In 


addition to sorting criteria, a window can contain matching criteria. This is set by using the “view tools” 
and is part of a custom view. T his sie can be ought of as a “boolean sort” where all objects that 


Everything Mover moves within S (the “System” amesuitcases) can be moved out of 
these containers into folders or volumes. When an object is moved out it becomes a separate file. 
Although the representations of these external objects are different, they still behave the same way as ob- 
jects in the Mover containers. This means that we define a “standalone” file format for each thing that 
Mover moves. 

Desk accessories will not have have to be moved into and out of special Mover containers often, 
since they can be launched directly by the Finder, like applications. Note that this is true of a desk acces- 
sory in a special container, as well as a standalone one. 

Note that Mover includes support for moving ‘sfnt’ resources for Bass (without crashing, if possible). 


Devices 


In addition to the trash, another icon will appear on the desktop, along with all of the disks. This is the 
devices icon. It will contain an icon for each attached printer or other device. The connection to the de- 
vice will be established with a “connection” tool which will use a graphic interface (plugging cords in) to 
describe which devices are attached to which ports on the machine. In addition, local devices can be 
given names and renamed, much like files or AppleTalk devices.’ 
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Network 


Inside the devices icon is an icon that represents the AppleTalk network Cif one is attached). The network 
works much like a disk or folder. At the top the network hierarchy what you see when you first open it) 
is a set of zones Cin a multi-zone network). In each zone is a set of icons which represent named net- 
work entities such as LaserWriters or AppleShare servers. These are viewed much like files, and can be 
rearranged, sorted, searched, etc. Positions of items within network windows are stored locally, but at 
some future date they may be stored on the network. When a standard network map C‘geography serv- 
er”) is available, it will be downloaded and used to display network windows (if the user chooses “View 
by Map”). 


Cross-Network Sofas 


Note that sofas are especially important for network objects. 

A user can find a printer he prints to often, and drag it onto his hard disk. This creates a sofa for that 

printer which can be used to print at any time by dragging a document there, or by choosing it as the 
“current printer”. 

Another user might create a sofa for a document that changes often, or that is shared by multiple 
people. If the document is on an ee server, the server is Rpecuerner| mounted when the sofa is 
opened. Note that there i 
server. (This goes away V 


bridalVeil Falls B= 


Gasséeville . EtherKnott BridalVeil Falls 


+ oo 


Global Chooser Strategy 


GG 


Bubb 3 The Commies Net Com 


naan - droppings 


© EtherKnott 


ES 2nd Floor ES DeaAnza Ill BRC Central 
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Printing 


Since printers appear as icons in the new Finder, we introduce the concept of dragging a document to a 
printer to print it. This involves switching temporarily to that printer as current printer, and invoking the 
application to do the printing. Opening the icon for a printer will show the queue of documents waiting 
to print (replaces PrintMonitor). Choosing a printer is done by clicking on it and choosing a menu item. 


The icons for printers are found within the devices container (discussed above), but sofas for the printers 
can easily be put on a disk, or in a folder with files that are often printed on that printer. 


Standard File — 


For many of the Finder features that we are adding, there is a related Standard File enhancement that has 
to be made. In addition, we are reducing the size of the Standard File package by using the List Manager 
and pop-up menus. 

Note that we are duplicating most of the features of Standard File in the Finder. This is an attempt to 
decrease the importance of Standard File, which is especially confusing, since it presents a second, less- 
flexible, view of Finder objects. 


Stationery 


We are implementing a Lisa-style 
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Icon Editing 


The icon for any Finder object will be editable. This is done by selecting the icon in the “Get Info” win- 
dow, and copying the icon, or pasting a new icon over it. Any graphics program, such as MacPaint, can 
be used to do the actual editing, In addition, we will supply a Finder extension that Cusing Steve 
Horowitz’ BitEdit package) provides FatBits-type editing of these icons. 


Extension Mechanism 


The new Finder has an extension mechanism. This provides a 
way to create custom Finders that are smaller, but have fewer 
features than the full product. We have designed the code so 


Mouse eliaerig 


that many key features can be removable extensions. Hi 2] 
Extensions will appear as icons inside the Finder icon. (Tablet) aususes 

In addition, we expect other groups at Apple to use our exten- © = Oo ® 
sion mechanism to implement system features tightly coupled Very Slow = Slow Fast 


with the Finder, for example Mail and Backup. It may eventu- 
ally be possible for third parties to do this as~y 


simplest, Finder extensior 
sion from an application if 
often, the data structures } 


Programmabili 


used to test the Finder as well as to improve the iareiace with MacroMaker and to experiment with fu- 
ture macro and scripting projects. 
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File System Enhancements 


Furnishings 2000 would benefit from some specific file system enhancements. The following are what we 
propose: 


“Desktop” Database 
We must have something to replace the functionality of the resource-based “Desktop” file. 
Must Have 

scales well 

public interface 


AppleShare functionality 


It must work well for many files, as the catalog does. It must have a public interface, since multiple appli- 
cations need to access it. It must have at least as much functionality as the AppleShare Desktop Manager. 


Would Like 


smaller/faster 
extended file infor 


We would like it to have a smallbr disk Gé Smory size (~24K Size tan the AppleShare Desktop 
Manager INIT. We believe that oge yy to sh\ink the disk size (~6K)Aand nfemory size (~8K) is to use an 


mance, 


We would like the maintenance of the application folder cache to be automatic. This might involve 
changes to SetCatInfo and Delete (at least) to call the Desktop Manager. Other groups have mentioned 
that they would like this kind of lists for other types of files (Diet Coke publications). 
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Sofas 
We must have file system support for sofas in order to create a robust implementation. 
Must Have 


CreateReference 
MapReference 


We must have a CreateReference call to change a file so that it can be referenced by cNodeID. We must 
have a MapReference call which maps a previously registered cNodeID to a parID and fileName. | 


Would Like 
cNodeID calls 
SwapFiles 
additional “sofa” support 


We would like a new mode which accesses files by cNodeID so that we don’t have to convert cNodelDs 
to file names, and then have the file systerrreqnvert back again. We would like a way to swap the con- 


Must Have 


SearchVol 


Would Like 


Enumerate 
file-system-only Open 


We would like a variation of the indexed GetCatInfo call which returns results for several consecutive 
calls. This will improve performance for local volumes and especially for network volumes. We would 
like a new Open trap which does not attempt to open resource or slot drivers. This will get rid of bugs 
when manipulating files that are named the same as drivers. 
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AppleShare Enhancements 


Furnishings 2000 would benefit from some specific AppleShare enhancements. The following are what 
we propose: : 


Must Have 


MountServerVolume 
GetMountI nfo 


These two calls allow us to mount an AppleShare server volume programmatically. The GetMountInfo 
call gives us a block of information which describes a volume so that we can auto-mount the volume at a 
later time. Preferably, this block could be passed directly to MountVolumes so that we don’t need to 
know its format. 


Would Like 
SearchVol 


Enumerate 
“per-user” information 
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MultiFinder Enhancements 


Furnishings 2000 would benefit from some specific MultiFinder enhancements. The following are what 
we propose: 


Must Have 


custom Apple menu items 
“Launch” for desk accessories 


Since the new Finder allows users to customize the Apple menu for all applications, there must be a new 
MultiFinder call that allows the Finder to control the contents of the Apple menu. Each Apple menu item 
has a small icon and a name. When an Apple menu item is chosen, the Finder must be called to handle 
the item. 

The new Finder allows the user to launch a desk accessory anywhere, and each desk accessory will 
occupy its own layer. We have implemented this in the Finder itself, but it belongs as a MultiFinder ser- 
vice, available to all applications. This would take the form of a “Launch”-type call for desk accessories. 


Would Like 


“Open” and “Quit” puppet strings in MuftiFinder) 
“Shutdown/Reftart” call 
“Print” puppet strifg 


MultiFinder puppet string hanism. An impro\ed interfaceffo this/is needed to get this specific knowl- 
edge out of Finder and tg-attew applicajions other than thefFinderfo tell other applications to open doc- 
uments. 


cations other than the Finder Uim-w O restart the machine: (For example, the HyperCard group has re- 
quested such a feature). This functionality should be moved into MultiFinder. 

Finally, to implement printing when a user drags a document to a printer, we need to create a new 
puppet string mechanism to allow the Finder to cause an application to print a document. All of these 
mechanisms can be built so that knowledgeable applications can use a new IPC mechanism, rather than 
being “faked out” by the puppet string mechanism as they are today. 
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Printing Enhancements 


Furnishings 2000 would benefit from some specific enhancements to our printing interface. The following 
are what we propose: 


interface to choose default printer 
Since we are integrating the functionality of the Chooser desk accessory into the Finder, we will need to 
move the knowledge of how to “choose” a default printer there. This would be a good time to make a 


simple interface for choosing the default printer, so that we do not build too much specific knowledge of 
the printing system into the Finder. 
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1/12/89 
Donn Denman 


MacroMaker 1.1 ER 


Abstract: 


MacroMaker is a system utility program that allows a user to automate a sequence of actions. 
MacroMaker 1.1 will be supplied with the Big Bang System on the Utilities II disk. 
MacroMaker 1.1 will be an evolutionary step from 1.0, with mostly cosmetic changes and bug 
fixes, but few enhancements or new features. Development of MacroMaker 2.0 (a radical en- 
hancement) will progress in parallel. This document specifies the changes to be made for 
MacroMaker 1.1 


Functional Enhancements 


1. The MacroMaker window will be mode-less. (Yea!). The window will open up in the same 
layer that the user is in. When the MacroMaker window is open, but not on top the buttons 
- will be disabled. Also, selecting MacroMaker from a menu will switch you back to the 
layer that the MacroMaker window was opened in. 


2. MacroMaker will wade ol-bays. This yexent problem with clicks 


1. When MacroMak¢r is JE top-tyost window, it will take entire menu bar. This allows 
the use of a file e the file\switching fe e Apple menu for the 
“About...” item 

2. The tape icon in the menu bar Will no lofger flash g ord and playback, instead it will 
be animated. 


3. MacroMaker will be added to the Apple menu. 

4. There will be some changes to the way keystrokes are handled in the text fields. <Enter> will 
just select the entire field. <Return> will do nothing, unless in a multi-line field, where it 
will advance input to the next line. <Tab> will move to the next field and then select the 
entire field. 

5. Clicking on the editable field’s labels will select the entire field. 

Cosmetic Changes 

1. The tape icon beside each macro in the menu, will be removed. 


2. The tape player image will be adjusted slightly. We will fit 8 macros in the scrolling list 
(clipping to a round rectangle) etc. 
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3. The dialogs and alerts will be reviewed, with minor changes to the text, position of buttons, | 
etc. We will use a MacroMaker Icon instead of the Stop Alert icon, so that it is clear that 
the messages are coming from MacroMaker. 


4. The help dialog will have an outline around the button used to terminate help. This button 
was labeled “Cancel” but it will be changed to “Done”. 


5. The “Another File” menu item will be split into “Open” and “New” under the File menu 
(when MacroMaker is open). 


6. Highlighting on the keystroke field will be in the text highlight color (instead of inverting the 
field). 


Bug Fixes 


1. When storing over a duplicate item, MacroMaker now allows Cancel, but it doesn’t cancel 
previous duplicates. 


2. The problem with tracking buttons that close the window they are in, will be fixed. This hap- 
pens frequently with HyperCard... 


5. MacroMaker may be able 
| hidden. 


Internal Changes 


1. Patches will be added to AddResMenu, FindWindow, DrawString, MeasureString. For scroll 
bars, we will patch FindControl, SetCtl Value, GetCtl Value, and TrackControl. 


2. Patches will be removed from ClearMenuBar, SetMenuBar, TickCount. 
3. The MacroMaker menu will go in the system heap. 


4, The patch that MacroMaker puts on _Control to fix journaling will be moved into the system 
PTCH resource. 
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Features Beyond the Scope of Version 1.1 

1. Record mouse motion when the button is down. 
2. High-Level event recording. 

3. Editable Scripts. 


4. A full programming language and environment for scripting. 


Parallel Development Strategy 


We plan to pursue a parallel development strategy for version 1.1 and 2.0. The feature list for 

1.1 is rather conservative, so we have a high confidence that we can deliver on schedule. The 
features planned for 2.0 are quite ambitious, so we want to get started on them right away, hence 
the parallel development. The following list enumerates the pieces that will be a part of 
MacroMaker 1.1. 


Tasks 


¢ Finalize the specifi ation for all user-vis igible changes, asap. 


¢ Release a fully fundtione ed4 Ipha version. 
¢ Remain stable, able ip-rrebust release any time. 
¢ Test exhaustively. 


i 


¢ Marketing delivery decisions: 


Other Issues 

¢ Should a High-Level Message interface be included? 

¢ Moving functionality from the window to menus. 

¢ Option to hide the menu. 

¢ Option to record raw mouse motion. 

¢ Option to give warnings in dangerous situations. (e.g. window, menu not found). 
¢ Should we record Launch from Finder logically? 
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Es rit Control Panel Device ERS 


Steve Horowitz & Bryan Stearns 
MIS 27-AK, x43082 


Updated 13 January 1988, to describe Version 1.0a5 


Overview 

The Esprit control panel device contains controls for 
all Esprit-specific functions: screen contrast, RAM 
disk size, automatic wakeup, power settings, and 
modem port selection (The modem-related controls 
appear only when there is an internal modem in- 
stalled). 


aT i Control Pane! SSS 


Minutes Until Automatic Sleep 


1-2-4-8-15-30 
Harddisk (a 


0 Don’t sleep while charging 


Gia RAM Disk Size 


Changes to RAM disk size will take 
effect when you restart. 


Automatic Wakeup O Interna? 
=) G] 4 2:20PM fee fisce 
i 1/12/89 | Basen 
eS: El snenPhene Rost oles gas 


Temporary Note: Later versions of the Esprit control 
panel device will not appear in the Control Panel 
when not running on a Esprit; for testing, this 
version runs (nonfunctionally) on any Macintosh. 


Battery Settings 


To conserve the battery, Esprit can spin down the hard disk and put the machine to sleep after 
a period of inactivity. The time periods involved are controlled by the user with these two 
sliders. The checkbox controls whether this conservation should be ignored when the Esprit 
is connected to the charger. (If no hard disk is installed, the hard disk slider is not displayed). 


See the Power Manager ERS for more information on the Power Manager’s interpretation of. 
these settings, and for definitions of such concepts as “idle time” and “sleep.” 


RAM Disk Size 


This sets the amount of memory set aside for the built-in RAM disk driver. A pop-up menu 
allows several settings (based on the machine’s RAM complement), None, and Other... (a 
dialog appears, allowing the user to set a specific value). 


A message is displayed with the RAM disk size pop-up giving information about changing 
the RAM disk size. Several messages are possible: 
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¢ IfaRAM disk is the current system disk, the message is The RAM disk is the startup 
disk; its size cannot be changed now. The menu will be disabled, but the value shown 
will represent current size of the RAM disk. 


¢ Ifa RAM disk is mounted, but contains open files (other than those associated with 
the Finder’s Desktop mechanisms), the message is The RAM disk contains files that 
are in use; its size cannot be changed now. The menu will be disabled as above. 


¢ Ifa RAM disk is mounted and contains no open files, or if no RAM disk currently 
exists, the message is Changes to RAM disk size will take effect when you restart. The 
menu will be enabled. 


¢ If no RAM disk is mounted, and the setting of the RAM disk size is not “None”, the 
message is The new RAM disk will be created when you restart. The menu will be 
enabled. 


¢ Ifno RAM disk is mounted, and the setting is “None”, the message is No RAM disk 
will be created when you restart. The menu will be enabled. 


If the user clicks Cancel, the value will revert to the size of the current RAM disk. If the user 
clicks OK, or if no RAM disk was mounted, the text of the message in the control panel will 
change to either The new RAM disk will be created when you restart. or No RAM disk will be 
created when you restart. depending on whether the setting is “None”. Further changes to 
the RAM disk size will result in no alerts or changes in messages (if the user closes & 
reopens this control panel device, it will act as though no RAM disk had ever been mounted). 


Refer to the RAM disk driver ERS for information on other aspects of RAM disk use. . 


Automatic Wakeup 

Hardware built into Esprit can turn on the machine at a specific future time, or whenever the 
phone rings. These two features are mutually exclusive: you can specify neither, either, or 
both features. 7 


One checkbox enables the “time” feature: a time and date appear next to it that the user can 
adjust (in the same fashion as the clock in the General control panel). The set time is 
remembered even if the checkbox is not set; also, changing the time does not implicitly check 
the box (though perhaps it should?). 
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The other checkbox enables the “when phone rings” feature. It will only appear if a modem 
is installed. 


No wakeup action is implied by this control; at the appointed time or ring, the machine will 
wake up exactly as if the user awakened the machine manually. 


Modem Controls 


These buttons toggle the state of the serial port, between control of the internal modem and 
the external serial connector. If the “Internal” icon is chosen, the internal modem is powered 
on and serial port A is routed to the internal modem, making the external serial connector un- 
usable (applications attempting to use serial port A will “see” a modem plugged into it). If 
the “External” icon is chosen, the built-in modem is powered off and Serial port A is again 
enabled for external devices. These changes take effect immediately. 


These controls appear only if an internal modem is installed. Also, these controls.cannot do 
any kind of arbitration for the ports (or tell that a port is in use), as drivers other than our 
serial drivers are free to open the ports. Changing this control while a driver is open (not 
recommended) will probably act as though an external modem were suddenly attached or 
removed; this should be tested. 


fre controlled by the standard 
gm file. 
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Battery Desk Accessory 


Steve Horowitz & Bryan Stearns 
MIS 27-AK, x43082 


Updated 13 January 1989, to describe Version 1.0a5 


Overview 


Temporary Note: The human interface of the Battery desk accessory is at this moment under 
redesign, and will change significantly; thus, this “specification” is decidedly wimpy about 
the actual appearance of the accessory. | 


The Battery desk accessory uses a thermometer-style indicator to show the relative charge 
level of the built-in battery. An icon (currently a lightning-bolt), if as well as a state value 
indicating whether charging is currently in progress. A “sleep” button is provided to allow 
single-Finder users to put the machine to sleep without quitting the running application. 
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Topanga Control Panel Device ERS 


Bryan Stearns 
MIS 27-AK, x43082 


Updated 13 January 1988, to describe Version 1.0a1 


Overview 

The Topanga control panel device contains controls 
to change the width of the Topanga screen, for when 
the Topanga is connected to an NTSC monitor. 


2 Control ead SSS 
Ke 


Topanga Configuration 
@ Macintosh 


Normally, the Esprit display is 640 pixels wide by 
400 pixels high. Macintosh II monitors connected to 
Topanga will correctly display the Esprit screen 
image; however, NTSC monitors do not have the 
horizontal bandwidth (the left and right sides of the 
image would not be visible). 


een driver to use only the 
fe exact Size iS 512 pixels 
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PictWhap 
: | ERS 


Screen Snapshot as Pict 
from Bo3b Johnson 


WHOITIS: 
PictWhap is intended to be a replacement for the FKEY 3 screen anaseien The old FKEY 
saves MacPaint files. PictWhap will save the screen as a PICT file instead. 


WHY ITIS: 

The old FKEY 3 is limited in what it can do by the MacPaint file format. It cannot create 
pictures larger than an 8.5x11 page (at 72 dpi), and it cannot handle color. If your screen is 
wider than 576 pixels (72 dpi * 8.0 inches= 576 pixels), then the image is being rotated 90° 
which makes it harder to use. Color i out of the question So screen ‘snapshots on Mac IIs tend 


to just beep. In addiften; ¢ no jonger gv : sttgrves|Claris somewhat of an 
advantage to have System Software creafe their ‘les Apple tide stated rdpeatedly that the only 
file format we suppart is ve no ol nse twat format. A number of 
developers have added th g read PICT tilef amy(PixelPaint, PageMaker, 
MacDraw...), and w¢ shot syen more incentive. 


style PICT built wit! 
guage for size reasons, a 


DETAILS: 

A full color PICT can be a huge memory pig if the image is not nicely packable, and can be 
on the order of the size of the screen (307K for a standard Apple screen). In light of this and the 
big monitors that exist, PictWhap will use the QuickDraw bottlenecks to write the picture data to 
a file on the disk. This makes a memory monster into a quiet citizen instead. The PICTs that are 
created will be PICT 2 types on Color machines, and will be PICT 1 types on older machines. 
Thus color information will be saved on machines that support color, but the same mechanism 
will work for all Macs. For multiple monitor systems the entire desktop will be saved. A port 
will be opened to do the saving operation, which will allow the save to include the menu bar as 
well, since a port is full screen size. It will also be grown to include the other monitors, based on 
the GrayRgn, so this should work on third party monitors for the Plus and SE. The files will be 
created for Pat, which will open and display any PICT file. 
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ISSUES: 

If feasible, PictWhap will try to recover the ability to snapshot the screen when the menus 
are down. The idea is to set up a Time Manager task running in a block in the heap, so that it has 
its own QuickDraw world that will run at interrupt time. The snapshot could thus be created 
when the user let up on the Shift key. The Time Manager task (and block in the heap) can be re- 
leased by a Notification Manager request. None of this has been tried yet, but it should be feasi- 
ble. If not, we are no worse off than before, and at least we will have PICT snapshots instead of 
MacPaint snapshots. Use of MenuHook has been discouraged, which is why this somewhat 
roundabout approach is being attempted. 


The name of the file will no longer be Screen 0..9, to make it more obvious that something 
has changed. A logical (to me) choice is Picture 1..N, but Iam open for suggestions as long as 
there are reasons behind them. In addition, the name of the file will be in a STR resource in the 
system file, so that it can be localized. When a number needs to be added to the end of the name, 
it will be added with something like NumToString in order to get a localized number. 


One slightly sick thing the FKEY needs to do is to play with a cursor hook while it is doing 
its job. Since the Picture eats via medehee vil ShieldCursor, the saved pictures end up with 
no cursor in them, which m@ekes sing gnapshge : rep jieldCursor hook 


PictWhap. Pat will allow fe 
scrolling around the entire sgwe 
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Pat | 
ERS 


Pictures and Text 


from Bo3b Johnson 
WHOITIS: 
Pat will be an application to display standard documents on the Macintosh: 
1. PICT files. 
2. MacPaint files. 
3. TEXT files. 


3. TeachText files. 
5. Styl TextEdit. 


Pat is intended to simplify the user’s view of displaying strange documents by creating a sin- 
gle program that can display a number of formats. Pat will be a read-only program, not an editor 
of the various formats. In addition to dis playing all the oe formats, Pat will allow some 

2 : and-blocks of Text can be 


the 8.5 x 11 page fortyatéf MacPaint. In ad dition, we hayé definéd and explained to the world 
that the PICT file is the only standard format Apple suppOrts; ygt we have no program to read 
PICT files. 


ple screens, and will wa acs. The next logtes wis to have a PICT reading program 
to be able to display/print/convert those PICT snapshots. This is Pat. 

Since Pat will do pictures, for compatibility it is also logical to allow Pat to read MacPaint 
files. 

TEXT is another standard format, so Pat should be able to show text files as well. 

Again, logically, since Pat will show PICT files as well as TEXT, Pat should also show 
TeachText files to make a single display program from the user’s view. 

Finally, since we have defined the ‘styl’ standard for TextEdit, we should have some tool to 
display it. 


HOw ITIS: 

Pat will be written using MacApp 2.0. This buys us a maximum of user interface for little 
work, and Text handling almost for free. This also buys us a larger program than TeachText, but 
with more universal functionality. Handling the Clipboard is a simple addition to a basic 
MacApp program, including selections. The most difficult aspect of Pat will be implementing 
the display of TeachText documents, but this should be relatively straightforward using the same 
techniques as TeachText itself. 
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DETAILS: 

Printing of any of the documents will be done with the standard printing object of MacApp, 
including the PICTs. This means that the printing will be on a Bitmap level for pictures. 
Selections of a displayed PICT can be copied but will be converted to a CopyBits type of PICT, 
which is a BitMap. If an entire PICT is selected, the printing and copy operations will use the 
PICT as it stands. If it were a MacDraw style PICT it would remain that way. The PICTs can 
easily be read using bottlenecks to minimize the memory usage. The pictures interspersed within 
text in TeachText documents will be individually selectable. It will be possible to select the text 
or the picture, but not both at one time. Pat will probably end up weighing in at about 90K, so 
making room on the system disk should be considered in advance. Pat will use the MacApp fail- 
- ure handling mechanism to make for a robust program that can function properly in small 
amounts of RAM (like 128K). Due to the large size of potential Bitmaps being displayed, update 
events will likely be done by reading the bottlenecks again. This may make updates slow. 
Whatever RAM is available however will be used as an offscreen buffer to allow for CopyBits 
type fast updates. The display will have a buffer that is the same size as the window (if avail- 

able), to allow for fast updates, but slower scrolling since the scroll will reveal new areas that 
will need to be read through bottlenecks. 


ISSUES: 

1. With the current medhanism_ of bund a dggument with more 
than one application. This js ba : fouble click on 
strange documents. The do - be seine, in Pat, but the’diregf association is lost. 
The use of Sofas in NuFindk attexiate thi ay, by afowing a Sofa of Pat to 

_ be next to the icon they wisk 
2. ‘styl’ TextEdit i isa fug i ; e t formats for ‘styl’ text, 


would be to use the 
MacWrite file format, but & t. This would also buy us 
the standard display of Mac efiles_meking it easier for mito don’t have MacWrite. 

3. The RAM usage is not a clear win, over slow update events, so perhaps 1 it should be the 
other way around, with a larger SIZE and fast updates. The problem comes in trying to handle a 
three monitor Mac II with a Kong. The surface area saved will be large. 

4. If we start getting into other file formats, like MacPaint and MacWrite we should probably 
do other ‘standard’ formats like TIFF and EPSF to be fair to all the competitors, although it 
doesn’t give anyone an advantage to have us display their document format. 
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CyberBash 
ERS 


System Testing via Applications 
from Bo3b Johnson 


WHOITIS: 

CyberBash is intended to conceptually test the operating system; as opposed to test programs 
that exercise specific managers or ROM routines. CyberBash will be a large application that ex- 
ercises as much of the ROM as possible. Not incidentally, CyberBash will be a game. 


WHY ITIS: 

Applications naturally exercise the operating system in a ‘can I build something useful’ fash- 
ion. Test programs have their place, but don’t exercise the conceptual/design level of the system 
managers. The operating system is composed of numerous routines that are intended to reduce 
the number of things a programmer has to do in order to provide specific functionality. To deter- 
mine if a given tool in the ROM meets this desirable goal, an application can attempt to imple- 
ment that functionality. While building a useful program, the programmer often finds parts of 
the OS that are hard to use, incompfetey or require access to privileged information. This is the 


problems for devd opens CyberBash js a gan St, a game is sufficiently 
malleable that it cf Ally f der © test pieces of the operat- 
ing system. Got MTA LCT te A new asp t of fle game can be implemented 
to exercise it. Sedond At haven’t been tried before. A 
number of application be one of the first to try to cover 
animation and sound ‘ ber of pieces of the program may 
be useful for thi r than playing thg game. An/Animafion Manager is something that 
could give deve acing better user ffedback/in response to commands, or to pro- 
vide for help systems thas i erform a command. Finally, it 
doesn’t hurt to havhe icati . Thi esitunlikely that we will compete with the 


developers, and makes it more fikely t that the application will be extended to try out new features. 


HOw ITIS: 

CyberBash will be written mostly in MacApp 2.0. This helps exercise our development 
tools as well as the system. Since MacApp is one of our premier development tools, it also 
makes sense to try to stretch the limits of how MacApp was expected to be used. The applica- 
tion will attempt to be as polite as it can, but use the system to the fullest. 


DETAILS: 

CyberBash will be an extension of an old Apple II game called RobotWar. The basic idea is 
to write a control program for a set of robots. The robots run about in a square battlefield. This 
is a gladiatorial contest, so the last robot standing wins. CyberBash is a programming simulator. 
The user of the application will write programs in a specialized robot language. Once the user’s 
program is done they no longer have any control of the robot during the battle. The outcome 
depends upon how the robot was programmed. The premise is simple: write a robot program 
that can defeat any other robot program. 
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Pieces of the operating system that will be exercised: 


MultiFinder to open documents, and to be able to utilize background time in a 
transparent fashion. 

‘styl’ TextEdit will be used for the editor. It will also include pictures in the text, 
and real tabs (implies rulers). 

The Notification Manager will be used to notify the results of the background 
processing. 

The Sound Manager will be used to generate noises and music. These will all be 
set up as ‘snd ' resources, and use the multiple channels to overlap sounds that 
can happen simultaneously. 

Color QuickDraw will be used where available to draw and animate color pieces 
on a colored field. In addition, the editor will allow for the use of color fonts. 
This includes QD-32. 

The Palette Manager will be used to handle color arbitration for the environment, 
especially 16 color mode. Color table animation will be used if possible. 

Printing will be used by having to print document listings, including graphics and 


styled text. 
AppleTalk will be used to perform sirgltaneous 
chines across the . All users pill seefthe same results at the 


Ginsu printing will be used when available. 

Since Pink will be object-oriented as well, it should be possible to port the appli- 
cation when the Pink toolbox is functional. 

Etc. 


ISSUES: 

Since a basic part of the CyberBash design is a compiler/translator of the robot programs, it 
is logical to extend the model to include things like the communications scripting language being 
implemented for MacTerminal, and a possible scripting language for macros that MacroMaker 
could execute. Since this will be done in Object Pascal, it should be possible to extend the model 
to include other languages (not just the robot language). This is another tool that might be useful 
for developers if it were available in the System. Imagine a document that when played back 
shows you exactly the sequence of operations you need to perform, by running a Macro to run 
the application through its paces. 

The animation section of the program must be high speed in order to produce a convincing 
display. The display will also be double buffered to avoid flicker. Both of these pieces are 
things that could conceivably be added to the System. The former to provide for better graphical 
feedback, the latter to help all programs avoid annoying flicker. 
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The translator also will be doing translation and parsing while the user is typing. It is con- 
ceivable that some of the lessons learned here can be applied to Q and future development sys- 
tems. 

It isn’t clear what to do if the System does not provide enough functionality in a specific 
area. The current plan is to come up with a way to resolve the problem, and give the information 
to the appropriate authorities to be included in future System revisions. At the same time, the ap- 
plication cannot be put on hold, so a workaround will be used until the System is revised. This 
applies to things like required use of low-memory variables, being forced to be 32-bit dirty, writ- 
ing outside the window and so on. This technique can hone our set of Macintosh Rules, and 
clear out some of the fuzzy aspects that developers currently have to risk compatibility using. 


For more information about the design of the CyberBash game itself, contact Bo3b Johnson or 
Darin Adler. 
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Laser Writer Font Utility 2.0 ERS 


FINAL DRAFT — 9/18/88 
by Eric Babinet 
Adopted by Dave Owens (x4-3391) 11/88 


In order to accommodate the forthcoming LaserWriter Il NTX-J and a number of PostScript ROM 
changes from Adobe, a few enhancements will need to be made to the LaserWriter Font Utility. 
Version 2.0 of the LaserWriter Font Utility will be completely backwards compatible and will 
incorporate the following changes: 


1) Backup utility for Japanese font. The LaserWriter II NTX-J will be shipped with a hard disk 
which will already have the Japanese Kanji font on it. One enhancement to the utility will allow 
the user to backup the Kanji font onto 3 1/2” floppies or to another hard disk attached to the 
printer. It will also allow the user to recreate the Kanji font on a hard disk attached to the printer 
from a set of backup floppies. 

The visible changes to the program due to this enhancement will be as follows: 


ise i selected printer 


b. This menu will havé two items,“Backup Japanese fony..” ay “Restore Japanese font...’”. If 
the currently selected printertfaxthe KanjNont on it's hard g e “Backup Japanese font...” will 
appear normal and the<Kestore Jayanese foht...” will be f If it doesn't have the Kanji font, 
but it does have a hapdedisk, then thp “Restofe Japanese font...” Jtem will appear normal and the 

Any hard disks attached, then both 
items will be dim xd. The progrgfn is beiy’g designed/so that ft will be very easy to add resources 


font....”’ and sR signe 


c. Choosing the “Backup Japanese font...” item will bring up a modal dialog that will require 
the user to choose (using radio buttons) between backing up the Kanji font to 3 1/2” floppies or to 
another hard disk attached to the printer. If there is only one hard drive attached to the printer, the 
hard disk option will not be available and this dialog will serve mainly as a confirmation dialog. 
There will be a help button if the user needs more information and a cancel button if the user 
decides to abort the backup. The help screen will provide details of what is required for each 
backup. If the user clicks OK, the application will verify that all the required files exist on the 
printer's hard disk. If this succeeds, the process will continue as described below. 


d. If the user has picked the backup to floppies, he/she will be told to label the first disk 
“Japanese printer font - 1”, and to insert it into the disk drive. The disk will then be initialized, and 
the application will begin uploading files from the printer to the disk. No indication as to what 
specific files are being copied will be made. However, a message saying that the font is being 
being backed up will appear. This message will also display the number of files that still need to 
be copied. When the first disk is full, the application will tell the user to label the second disk 
“Japanese printer font - 2” and to insert it into the drive. The application will initialize the second 
disk, and will continue uploading files. This process will continue until all necessary printer files 
have been copied. (The number of disks required will vary depending on what density disks the 
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user is using.) When the last file has been written, the application will prompt the user to reinsert 
the first disk, “Japanese printer font - 1”. The application will write some information on the first 
disk indicating that the backup was successful. This is a program check so that backups which do 
not run to completion cannot later be restored. After this, a message will appear telling the user 
that the backup was successful. If ever the backup should fail, either because of a disk error, a 
printer error, or the user canceling, a message will appear indicating to the user that the backup 
was not completed. 


e. If the user had picked the backup to another hard disk option, a different modal dialog will 
appear requiring the user to select the radio button of the SCSI drive to which the font should be 
backed up. The only buttons which will be selectable will be those that correspond to a SCSI disk 
attached to the printer, however, not containing the font being backed up. There will be a cancel 
button if the user would like to abort. If the user clicks OK, the application will initialize the hard 
disk, and will copy all relevant files onto the backup hard disk. Status messages will appear while 
this is being performed. If successful, a message will appear indicating that the backup was a 
success, and that before using the printer again, the printer should be turned off and the backup 
drive disconnected. 


f. Choosing the “Restoredapanese-font---“itern from pre-mer orHtA up a dialog 
asking the user to select the pri s hard ae (igentifieg which he/she 
would like to restore the Japanese edialop will let the : fe which does not 


already have a composite fo it. Since the only composife feat ae aAser gy bald have at this 
point is the Japanese font, thip will / 


printer. If the user clicks OK] the appeation will pxoceed to initiali lected hard disk. If this 
succeeds, the user will be prosapgéd to inse labeled “Japghese pyinter font - 1”. The 
application will begin copyin d isk to the pyinter's ard disk. When all files 
from the first disk have beey Me appligation wijfl prompt f¢r the digék labeled “Japanese 
printer font - 2”, etc., etc., ul til the testorgyion is complete or fails. If ifsucceeds, a message 
indicating this will appear. {ll appear tefling the fiser that the restoration 
failed. The user will be required To~mse eCisks in the ordertharthey were created, and the 


program will have ways of checking the igtearity of the backup disks. 


2) Enhanced printer disk initialization. Among the improvements to PostScript is the capability 
of individually initializing hard disks attached to the printer. This capability needs to be capitalized 
on by the utility so that a user of the LaserWriter II NTX-J who would like to add additional drives 
to his/her system will not be required to restore the Kanji font. 

This change will involve extending the Initialize Printer's Hard Disk dialog to include a check 
box for each SCSI drive that can be attached to the printer (i.e. boxes with drive 0, drive 2.,...,drive 
7) and two radio buttons, “Initialize all disks” and “Initialize some disks”. If the currently selected 
printer has no hard disks, then everything will be dimmed. If the selected printer has hard disks, 
but does not have the capability of individually initializing hard disks (i.e. the LaserWriter II 
NTX), then the “Initialize all disks” will appear normal and selected, and everything else will be 
dimmed. If the selected printer has the capability of initializing disks individually, both buttons 
will have normal highlighting, and the “Initialize all disks” button will start off being selected. If 
the “Initialize some disks” button is selected by the user, the appropriate box for each attached 
hard drive will be highlighted, and the user can check whichever ones he/she wants to initialize. 
Clicking on the “Initialize” button will then initialize the appropriate drives. 
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3) Revised help screens. Help screens will need to be revised to reflect the enhancements to the 
program. A second screen will be added to the help available when the application first starts up. 
This screen will basically explain the Languages menu. The Initialize Printer's Hard Disk help 
screen will need to be updated. Also, new help screens will be added in all of the places explained 
above in the backup utility section. 


Apple Confidential 


Close View 1.1 ERS 


Darin Adler 
Saturday, January 14, 1989 


CloseView 1.0 cannot be turned off permanently. This makes it difficult for a sighted person 
who wants to use Close View occasionally to use it. It has to be removed from the System Folder 
to disable it. This was an intentional feature. The idea was that someone who needs Close View 
to see the screen of the Macintosh can’t see the On/Off buttons and the Apple menu to bring up 
the Control Panel and turn CloseView on. 


To make Close View more useful when a machine is shared between visually-impaired and 
normal users, the On/Off state will now be saved, but a key equivalent (Command-Option-O) 
will be created to allow the impaired user to turn on Close View without seeing the screen, even 
when Close View is off. 


In addition, the Close View Screen will be redes¥gned to 
improve it’s appearance. 


include the new key equivalent and to 


PS: Lots of bugs will be (hdve begz 
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1/12/89 
Donn Denman 


MacroMaker 1.1 ERS 


Abstract: 


MacroMaker is a system utility program that allows a user to automate a sequence of actions. 
MacroMaker 1.1 will be supplied with the Big Bang System on the Utilities II disk. 
MacroMaker 1.1 will be an evolutionary step from 1.0, with mostly cosmetic changes and bug 
fixes, but few enhancements or new features. Development of MacroMaker 2.0 (a radical en- 
hancement) will progress in parallel. This document specifies the changes to be made for 
MacroMaker 1.1 


Functional Enhancements 


1. The MacroMaker window will be mode-less. (Yea!). The window will open up in the same 
layer that the user is in. When the MacroMaker window is open, but not on top the buttons 
will be disabled. Also, selecting MacroMaker from a menu will switch you back to the 
layer that the MacroMaker window was opened in. 


2. MacroMaker wil understand scroll-bars. Thjs will ae eund the cuirent problem with clicks 
in the scroll be not playing back when th¢ winde sws——We spould be able to 


2. The tape icon in the enu_barsvttfno longer flashdertrg-trecord and playback, instead it will 
be animated. 


3. MacroMaker will be added to the Apple menu. 

4. There will be some changes to the way keystrokes are handled in the text fields. <Enter> will 
just select the entire field. <Return> will do nothing, unless in a multi-line field, where it 
will advance input to the next line. <Tab> will move to the next field and then select the 
entire field. 

5. Clicking on the editable field’s labels will select the entire field. 

Cosmetic Changes 


_1. The tape icon beside each macro in the menu, will be removed. 


2. The tape player image will be adjusted slightly. We will fit 8 macros in the scrolling list 
(clipping to a round rectangle) etc. 
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3. The dialogs and alerts will be reviewed, with minor changes to the text, position of buttons, 
etc. We will use a MacroMaker Icon instead of the Stop Alert icon, so that it is clear that 
the messages are coming from MacroMaker. 


4. The help dialog will have an.outline around the button used to terminate help. This button 
was labeled “Cancel” but it will be changed to “Done”. 


5. The “Another File” menu item will be split into ee and “New” under the File menu 
(when MacroMaker is open). 


6. Highlighting on the keystroke field will be in the text highlight color (instead of inverting the 
field). 


Bug Fixes 


1. When storing over a duplicate item, MacroMaker now allows Cancel, but it doesn’t cancel 
previous duplicates. 


2. The problem with trackiae-butte 


be fixed. This hap- 


pens frequently with ] 
3. We will try to fix the bu some way to put 
the resource map intojan i e wif be unusable 


5. MacroMaker may be a mi , ven when the menu bar is 
hidden 
6. Fix the bug causing MacroVfiakerte-leop, when playing ¢ it another layer’s window. 


7. Ensure compatible versions of MacroMaker during switch-launch. 


Internal Changes 


1. Patches will be added to AddResMenu, FindWindow, DrawString, MeasureString. For scroll 
bars, we will patch FindControl, SetCtl Value, GetCtl Value, and TrackControl. 


2. Patches will be removed from ClearMenuBar, SetMenuBar, TickCount. 
3. The MacroMaker menu will go in the system heap. 


4. The patch that MacroMaker puts on _Control to fix journaling will be moved into the system 
PTCH resource. 
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Features Beyond the Scope of Version 1.1 

1. Record mouse motion when the button is down. 
2. High-Level event recording. 

3. Editable Scripts. 


4. A full programming language and environment for scripting. 


Parallel Development Strategy 


We plan to pursue a parallel development strategy for version 1.1 and 2.0. The feature list for 
1.1 is rather conservative, so we have a high confidence that we can deliver on schedule. The 
features planned for 2.0 are quite ambitious, so we want to get started on them right away, hence 
the parallel development. The following list enumerates the pieces that will be a part of 
MacroMaker 1.1. 


Tasks 
¢ Finalize the speci 


¢ Staffing (no otic anticipated). : 
¢ MultiFinder, DA Handler, and System compatibility. 
¢ Marketing delivery decisions. 


Other Issues 

¢ Should a High-Level Message interface be included? 

¢ Moving functionality from the window to menus. 

¢ Option to hide the menu. 

¢ Option to record raw mouse motion. 

* Option to give warnings in dangerous situations. (e.g. window, menu not found). 
¢ Should we record Launch from Finder logically? 
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Close View 1.1 ERS 


Darin Adler 
Saturday, January 14, 1989 


CloseView 1.0 cannot be turned off permanently. This makes it difficult for a sighted person 
who wants to use Close View occasionally to use it. It has to be removed from the System Folder 
to disable it. This was an intentional feature. The idea was that someone who needs Close View 
to see the screen of the Macintosh can’t see the On/Off buttons and the Apple menu to bring up 
the Control Panel and turn Close View on. 


To make Close View more useful when a machine is shared between visually-impaired and 
normal users, the On/Off state will now be saved, but a key equivalent (Command-Option-O) 
will be created to allow the impaired user to turn on CloseView without seeing the screen, even 
when Close View is off. 


@ Kedesigned to in e the new key equivalent and to 
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improve it’s appearam 
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Overview 


This document describes the software environment for the CMOS 
68000 based Macintosh personal computer. The software comes in 
two sections - 1) 256K of ROM on the main logic board, 2) one or 
more 800K or 1.4M 3.5" disks. 


The intent of this project is to provide the full functionality of a 
Macintosh SE in a portable, battery operated package. Compatibility 
with the current Mac SE software base is a primary concern and will 
the highest priority whenever possible, except where it interferes 
with full functionality or significantly degrades battery lifetime. 


This project is currently known as the Esprit project. The system 
software (sections 1 and 2) will be referred to as the EspritSSW in 
this document. 
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ROM Contents 


ROM Image - The EspritSSW ROM image is 256 bytes in size. It is 
stored as two 1Mbit CMOS ROMs on the motherboard. A ROM slot 
exists on the motherboard that allows ROM upgrades in the field. 


Mac SE base - The EspritSSW is based on the 256K Mac SE ROM. All 
known patches are to be rolled in. New versions of TextEdit and SCSI 
Manager are included, the addition of the EDisk driver, as well as the 
inclusion of the Background Notification Manager in ROM. 


General Port - The ROM has been converted to accommodate the 
different hardware environment and to provide the features and 
functions for portability. This includes relocation of the ROM, 
relocation of the screen, the size of the screen, etc. 


Power Manager - 


Manager, takes over igns and adde- ew-enes ty the Mac 
hardware environment is-mracessor repli fal Ame clock 
and the Apple Desktop It adds power /Zlock control 
for peripheral subsy$term d controls she Pattery and 
charger system, providés a wale up tjmer facilifv, cofitrols LCD 
screen contrast, ang | port/connegtions to /an infernal modem 
The hardware interface to anager /s thropgh a port on the 
VIA. The software | S is thrqugh the A rap echanism, a 
Power Manager trap prove necessary a Drivers will be 


modified to call the Power Manager to turn on and off their 
respective peripheral chips. 


Apple Desktop Bus - Some changes to the ADB state machine code 
are necessary to use the Power Manager as a smart transceiver. 


Real Time Clock and Parameter RAM - As the RTC functions 
have been taken over by the Power Manager, a new interface to the 
clock and parameter RAM has been developed. A subset of parameter 
RAM (128 bytes) is stored within the Power Manager. Clock and 
parameter RAM traps have been modified for the new environment. 


Sound Manager - As Esprit has the same Apple Sound Chip as the 
Mac ][, the Mac ][ sound manager is included. Some modification was 
necessary for the driver to function in the portable environment and 
for the Apple Sound Chip to function on a 68000 bus. 
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SCSI - A new SCSI manager that simplifies use of the SCSI port 
while retaining compatibility with the previous version. The SCSI 
manager also contains modifications to correctly control hard disk 
power and spinning down the disk when not in use. 


AppleTalk - Like all other drivers, the AppleTalk driver has been 
changed. In particular, to control power to the serial communication 
system. 


Serial driver - This driver will be modified for portability, which 
for the most part involves adding calls to the Power Manager to 
enable the serial port system. 


SWIM Driver - This is a completely new floppy disk driver which 
includes support for the MFM compatible drive. Power control calls . 
are included also. 


RAM and ROM Expansion - Memory expansion can be accomplished 
two ways. Internal expansion will be done using daughter boards in 
the machine and is already supported by the ROM. Simple memory 
mapping will be supported to add the external RAM to main memory. 
As mentioned above, the ROM slot is available for ROM upgrades and 
for ROM extensions. | | 


EDisk Driver - Support for SLIM cards and internal RAM and ROM 
disks is provided by the EDisk driver. 


Diagnostics - New diagnostics and test routines are included from 
Test engineering. The base for the Test Manager is the Mac Il version. 


Time Manager - A new Time Manager, recently released on System 
6.0.3, is in ROM. 
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System Tools Disks 


System Tools Software Conversion - A possible stripped down 
version of the system disk may be needed. This version would 
contain only those item required for Esprit and would be easier to 
place in the small (256K) battery backed up SLIM RAM cards that 
substitute for floppies. If not, the universal disk will be used. 


Control Panel - Several additional resources will need to be added 
to the contro! panel i.e. an Esprit CDEV: support for the internal 
modem, time-out for sleep mode, battery and charger monitor, wake 
up timer support, time-out for hard disk spin down, RAM disk sizing, 
and screen contrast control. A battery monitor DA will be pean: 
that can be left on the desktop at all times. 


the Sound Managen. 
environment. 


support low power and 
supporting sleep alerts. 
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Appendicies 
Power Manager ERS 


PowerMgr ERS 
Sleep/Idle/WakeUp and Sleep Queue ERS 
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SOFTWARE SPECIFICATION 


REVISION 3.2 
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ABSTRACT 


This document describes the inner workings of the Esprit 
Power Manager (herein known as the PMGR) firmware. Included are an 
introduction, a theory of operation, and a complete description of the 
format and syntax of the PMGR command set. The intended audience 
includes Macintosh OS firmware writers and third party developers 
interested in fully exploiting the unique capabilities of Esprit. 
Readers should already be familiar with the Esprit External 
Reference Specification. 
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INTRODUCTION 


The PMGR is an intelligent assistant to the 68000 CPU. It 
monitors the battery state of charge, handles power consumption of 
peripheral subsystems, contains the real time clock, interfaces to 
the internal modem, and acts as a Apple Desktop Bus transceiver. 
The PMGR is implemented in a Mitsubishi 50753 single chip 
microcontroller. This chip contains 6k ROM, 192 bytes RAM, 36 
general purpose |/O lines, three timers, and an eight bit A/D 
converter. The 50753 is fabricated in CMOS and consumes three 
milliamps of current at 4Mhz. 
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THEORY OF OPERATION 


The PMGR firmware consists of three main sections; receiving 
and acting on commands from the 68k, handling Apple Desktop Bus 
communication, and timer and periodic system monitoring. The PMGR 
waits for commands to be sent from the 68k, receives them, acts 
upon them, then returns a reply (if any). Once every 1/60 of a second, 
the PMGR stops receiving commands and executes its periodic 
functions. These functions include updating the real time clock, 
checking the battery, etc. The last periodic performed is to send the 
auto poll ADB command, if one is pending. 


Command Receiving 


The 68k and the PMGR porn Uinieate over an eight bit parallel 
bus, with a A he VIA is used 


process command 5 
happens, the I/O channel is closed and the PMGR will not respond to 
handshake requests until the ADB and other periodic routines are 
completed. 

Figures 1 and 2 illustrate the handshake sequence. The 68k 
begins the handshake by placing the data on port A and lowering 
68req (VIA bit 0, port B), then waiting for the PMGR to lower PMack 
(VIA bit 1, port B) indicating that it has read the byte. Once PMack is 
detected low, the 68k raises 68req. The PMGR finishes the handshake 
by raising PMack. All data sent from the 68k to the PMGR is sent this 
way. 
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t01t1 112113 4 
—-68req 


PMack 


DATA —-@otnIAND>—€ COUNT > CATA 


tO - 68req de-assert to PMack assert, command- 50us min 100us max 


t1 - PMack assert to 68req de-assert - 10us min 20us max 
t2 - 68req de-assert to PMack de-assert - 50us min 100us max 
t3 - PMack de-assert to 68k assert - 10us min 20us max 


Apple Computer Inc. Confidential 5 


tO t1} t2its 


68req 

PMack 

DATA C REPLY Dmn€ COUNT Dm DATA Dome DATA) 

tO - PMack assert to 68req assert , reply- 10us min 20us max 
t1 - 68req assert to PMack de-assert - 50us min 100us max 
t2 - PMack de-assert to 68req de-assert - 10us min 20us max 
t3 - 68req de-assert to PMack assert - 50us min 100us max 


ADB and 

The PM contains all of the ADB/trans£eiver functions 
normally foufid in\the AUB trangceiver t does things ina 
slightly diffexent ackets/to be s¢nt out/on the ADB bus are 


sent to the PMGR within apeé6mmand, with th¢ ADB data contained in 
the data portion o ommand. Data received by the PMGR from 
ADB devices is buffered internally and once received, the data is 
stored until requested by the 68k. 

If a new ADB command was sent by the 68k during the previous 
command/execution sequence, the new command and its data is the 
next ADB command to be sent. If the “auto-poll" bit is set for this 
command, it will be sent automatically on all subsequent 60Hz 
clocks (this is known as auto-polling). 

If the ADB device has any data to return, the PMGR receives and 
buffers it, up to the maximum of eight bytes. When the data is 
completely received, the PMGR interrupts the 68k by lowering PMint 
(a PMGR output wired to VIA input CB1). The 68k responds to the 
interrupt by reading the PMGR interrupt flag register to determine 
the source of the interrupt. Control is passed to the ADB interrupt 
handler which requests the data from the PMGR. Data received from 
the ADB device is returned by the PMGR imbedded in the ADB reply 
along with the rest of the ADB reply command data. 
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The 68k will also be interrupted if there was no reply from the 
device and the “auto-poll" bit is cleared, or a Service ReQuest (SRQ) 
condition was detected while sending the ADB command. 


Timer and Clock Functions 


A one second timer, based on the 60Hz frequency of the PMGR 
main loop, is used to generate the real time clock, act as a wake up 
timer, create the one second interrupt, and trigger battery, charger, 
and temperature monitoring functions. 

By using a crystal based external 60Hz clock as the trigger of 
the PMGR periodic functions, an accurate timer/clock is generated by 
counting each 60Hz clock. As each new second is counted, a number 
of periodic operations take He First, the real time clock and wake 


up timer (if enabled) are u ext, the Esprit power system and 
battery is checked jto determine | remaining battery poms and for a 
low power conditio tempprat ked at 


computer is to conserve Sty power. Esprit accomplishes this in a 
number of ways: powering off peripheral subsystems when not 
needed, slowing the 68k clock when full speed is not required, and 
powering off the whole system. 
The PMGR will send the system to sleep under either of two 
conditions, a very low battery, or by receiving the Sleep command 
from the 68k. The 68k sends the Sleep command when the Esprit 
operating system has determined that there is no user activity for a 
given amount of time or when the user decides to stop work and to 
shut down the system. Before sending the command, the operating 
system and drivers save whatever state necessary in RAM. These 
variables are used later to restore the system when power is 
restored. The PMGR sets a flag indicating that the Sleep command 
has been received and confirmed, then turns off all system power. 
At the end of the PMGR sleep code are two instructions that 
toggle one of the PMGR output lines. This line is connected to a 
circuit that disables the PMGR processor's own 3.9Mhz clock. This 
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essentially "stops time" for the processor, halting its execution and 
lowering its power consumption by two orders of magnitude. The 
processor internal state is frozen, with all internal RAM and control 
registers remaining intact. This is defined as the PMGR's sleep 
state, powered, yet stopped. 

The 60Hz external clock used as the basic PMGR time base, is 
also used to re-enable the 3.9Mhz clock. The rising edge of the 60Hz 
clock re-enables the 3.9Mhz clock, which starts the PMGR processor 
executing code. The PMGR resumes execution at the exact spot where 
it turned itself off and begins the wake up check loop. First, the 
clock and times are updated, then the environment is checked for a 
reason to wake up. 

There are three possible conditions that will wake Esprit once 
sleep has been entered: if any key is pressed on the keyboard, if the 
wake up timer is enabled and matches the real time clock, or if the 
Esprit internal modem is installed and up to watch for "ring 
detect". If anf dT yl 
itself and wak 
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OPERATING SYSTEM INTERFACE 


Traps and Parameter Blocks 


One new OS trap has been added to support the PMGR: _PmgrOp. 
This single trap provides access to all PMGR commands using the 
calling convention described below. 


Entry: ° AO = Pointer to PMGR parameter block 
Exit: DO = Result code (integer) 
Trap Macro: _PmgrOp 
PmgrPBlock = 
Record 


reply upon exit. je 

by pmgrXptr. Uponexit, pmgrer ‘ 

to by pmgrRptr. The pointers pmgrXptr and pmgrRptr, are the data 
transmit buffer and the data receive buffer pointers, respectively. 
The caller supplies the parameter block and buffer storage. 


Result codes 


noErr 0 

pmBusyErr -13000 ; Pmgr stuck busy 

pmReplyTOErr -13001 ; Timed out waiting to begin reply handshake 
pmSendStartErr -13002 ; Pmgr did not start handshake 

pmSendEndErr -13003 ; During send, pmgr did not finish handshake 
pmRecvStartErr -13004 ; During receive, pmgr did not start handshake . 
pmRecvEndErr -13005 ; During receive, pmgr did not finish handshake 


The _PmgrOp trap disables interrupts for up to 2 milliseconds 
for handshaking data. For a complete description of the Power 
Manager interface and command set, see the PowerMgr ERS. 
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COMMAND DESCRIPTION 


Power and Clock Control 


The Power and Clock Control commands ($1X), are is used to 
enable/disable individual Esprit subsystems. Esprit circuits that are 
not needed are powered off by the 68k to save power. Bits in the 
data byte sent with the command represent the PMGR output lines 
that control power (or clock) to peripheral devices and support 
circuits. 

Esprit device drivers are responsible for powering on and off 
their respective peripheral devices. The serial driver must 
enable/disable the SCC and the line drivers, the disk driver must 
enable/disable the SWIM, etc. Device drivers are also responsible for 
keeping the time that iy ovices are inna to a minimum in 


e following peripheral 
line drivers, internal 


their clock). Device enable/disable control comes in two forms, 
power control and clock control. Those devices that have system 
clock inputs are enabled/disabled by controlling their connection to 
the clock. They remain powered even when the rest of the system is 
off and therefore retain their state. Clock controlled devices do not 
need to be re-initialized when re-enabled, when their clock is turned 
off they retain their state. These devices are: SWIM, SCC,. 

The devices that do not have a clock input or do not have any 
state to retain are enabled/disabled by controlling their connection 
to power. These devices are: serial line drivers, -5 volts supply, +12 
volts supply, the ASC, and SCSI. In addition, there are two special 
cases: internal modem, and 68000. 

The internal modem has no clock input, and is enabled/disabled 
by controlling its power. Once the modem is powered up and 
initialized, it remains powered until it is no longer needed or until 
the system goes to sleep. During sleep the modem remains powered 
much the same as the PMGR, not functioning but retaining its state. 
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Powering up and down the 68k power grid is known as waking 
up and going to sleep. Included in the 68k power control are other 
system sections that the 68k uses when it is powered. These include 
the RAM, the ROM, and some of the control logic. Because these 
sections and the 68k receive power from the same point, controlled 
by the same PMGR output, they should be thought of as a single entity. 

Before the 68k can be powered down, those internal states that 
are not saved automatically must be saved in RAM so that it is 
available for restoring when Esprit wakes up (Esprit's CMOS RAM 
remains powered at a low level and therefore retains its contents 
even when the rest of the system is powered off). This includes 
system variables, peripheral device internal registers, and the 68k's 
own internal registers. The PMGR is then passed the command to 
power off the system. 

When power is restored, the 68k loads its internal registers 
from RAM, directs the device drjvess to restore their devices, and 
resumes execution 

When reset, 
enable all function 


the same functionality of tié ADB transceiver chip, but handles data 
transfer somewhat differently. Command and data transfer from the 
Esprit operating system to the bus and data returned from devices to 
the operating system are fully buffered. All ADB functions are 
supported, including bus reset, service request detection, and auto- 
polling. 

The command set for ADB operation consists of two functions, 
setting up a new command and reading the results of the ADB 
transaction. Actual ADB commands (talk register 0, listen register 
3, etc), and data are sent to the PMGR for transmission within this 
desktop command. Responses from devices are buffered by the PMGR 
until they are completely received, at which time the PMGR 
interrupts the 68k. Device data is returned in the ADB read command. 

The PMGR's auto-polls, that is, automatically sends the last 
command if the "auto-poll” bit has been set. As before, any data 
returned from the device is buffered and sent to the 68k on an 
interrupt basis. 
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The other ADB command reads the current status of the ADB and 
the ADB data last received from the ADB bus. This is the command 
issued by the system ADB interrupt handler to retrieve the data from 
an ADB device. 


Real Time Clock and Parameter RAM 


There are two real time clock functions: one to set ($30) and 
one to read ($38) the clock; and four parameter RAM functions: 
write/read the first twenty bytes of parameter ram ($31/$39) and 
write/read extended parameter ram ($32/$3A). 

The clock data is stored as a count of the number of seconds 
since midnight, January 1, 1904 (unsigned long word, four bytes). 

Only 128 bytes of the 256 bytes of extended parameter RAM are 

TTS The table below illustrates the 
r RAM 


$E0-$FF $60- $7F 


The original parameter RAM (20 bytes) does not map into the 
first 20 bytes of extended parameter RAM, it is actually broken up 
into two disjointed pieces within extended parameter RAM. The 
read/write commands ($31/$39) that handle old parameter RAM, 
automatically do the mapping into extended parameter RAM to 
get the right bytes. | 

It is important to understand that the Power Manager does not 
do the mapping for you when reading extended parameter RAM 
(commands $32/$3A). If bytes $70 and $71 of extended parameter 
RAM are wanted, the bytes that should be requested, as shown by the 
above map, are $40 and $41. Generally, is is not necessary to call the 
Power Manager directly when accessing extended parameter RAM. 
The operating system calls, ReadXpram and WriteXpram, do the 
mapping for you and should be the ones called when access to 
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extended parameter RAM is desired. 


LCD Screen 


The LCD screen commands ($4X), allow adjustment of the 
screen contrast and reading of the contrast value. The screen can be 
adjusted to any of 32 contrast levels with the set command. The 
contrast read command returns the current value of screen contrast. 


Internal Modem 


The Esprit's internal modem is controlled through the PMGR. 
The set ce command ($50), allows the 68k to power the 


whether or not a 
Since the m 


perhaps by opening.the serial driver. 

Whenever the mode powered, the Signals are re-routed 
from the selected external DIN connectors (modem or printer) to the 
modem. Cables inserted to the selected DIN connector are completely 
disconnected from the SCC serial port. The signals are reconnected 
to the port when the modem is powered off or changed to the other 
serial port. 

_ The ring wake up feature allows Esprit to be awakened by a 

ringing telephone when the ring detect wake-up flag is set. 


Battery and Charger 


Battery and charger functions ($6X), consist of a single read 
command. The read battery status command returns a status byte 
indicating the presence of a battery charger and the state of the bulk 
charge enable bit, a battery voltage measurement, and and machine 
temperature measurement. The battery voltage and temperature 
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measurement values are not processed in any way, they are the 
actual values read from the internal A to D converter. The operating 
system converts from raw value to battery voltage and temperature. 
Esprit operating system software regularly monitors the power 
level and alerts the user when it gets low. This allows the user 
some time to finish his or her current job and shut down, or to 
connect the battery charger. Two bytes of parameter ram are 
designated as threshold values (called LowWarn and Reserve). When 
the voltage value read from the A to D converter falls below the 
LowWarn value, the PMGR will alert the operating system of the 
situation by sending an interrupt. When the voltage value read from 
the A to D converter falls below the Reserve value, the PMGR will 


- shutdown the computer. The PMGR will not allow Esprit to operate 
‘until the charger is connected and the battery has been restored to 


greater than the LowWarn level. 
The temperature outjefrange sensing mechanism is similar to 


the battery thfesnold ‘ ® is stored in 
parameter ra erature the 
temperature vplug rom the A/to/D above lue, the system 
gets an interfup atic shutdown wi ur for temperature 
out-of-range 
Sleep 

When the operating System detefmimes-that Esprit should sleep, 


from either a user request, a time-out, or a low power condition, it 
sends the sleep command to the PMGR. Once the command is 
confirmed, power to Esprit is removed within 48 to 64 milliseconds. 

The Esprit operating system must be fully prepared before the 
sleep command is sent. The preparations include: the 68k saving all 
of its internal registers in RAM so they may be loaded when power is 
restored, the device drivers being called to allow them to prepare 
themselves, and any other precautions to insure that the system will 
resume unaffected. 


Interrupts 
There are three sources of interrupts from the PMGR: ADB data 
ready, low battery condition, and operating temperature out of range. 


A single command exists ($78) to read the PMGR interrupt register. 
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This register also contains a bit that indicates that either the 
machine has been powered up or it has been reset since the last time 
this register was read. 


Wake Up Timer 


The PMGR wake up timer may be used to wake Esprit at a 
predetermined time. There are three timer commands: set time, 
disable wake up, and read wake up time. 

Setting the wake up timer automatically enables it. When the 
real time clock reaches the timer value, Esprit will wake up. If 
Esprit is already awake, no action is taken. Disabling the wake up 
timer may be done by setting it to a time before the real time clock 
(sometime in the past) or with the disable command. The timer may 
only be enabled by setting a new,time. The wake up time and the 


enable flag may algo time wit d 
command. 

The wake up|time data format is the Same as t¥e rgal time 
clock, the count of jthebrfumber of\seconds since m January 1 
1904 (unsigned long : ) 


There are two sound-serntfol command one to read the 
state of the sound control bits and one to set them. First, a 
description of the sound control hardware. 

The key component in the sound hardware is a single bit latch. 
This latch is set whenever the Apple Sound Chip (ASC) is addressed, 
anywhere in its address space. The output of the latch controls 
power to the amplifier section of the sound circuit, as a result, the 
act of addressing the ASC automatically turns on the sound power. In 
addition to the sound latch is another line that can enable the power 
to the amplifier section independently of the sound latch. 

How it works: code that uses the ASC continues to do so | 
unmodified. The auto enable latch automatically gets set when the 
chip is addressed, which turns on the power to the sound amplifiers. 
Sound is made. 

As expected, leaving the sound on when not in use is 
undesirable and a great waste of battery power. To remedy this, an 
addition has been made to the Mac sound driver. There is a routine in 
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the sound driver called a "sniffer" that periodically checks the state 
of the sound hardware. The sniffer reads the state of the sound latch 
to see if anyone is using the sound hardware. If so, it turns on the 
sound power enable line then clears the sound latch. The sound power 
enable line keeps power going to the amplifiers even when the latch 
is cleared. 

The sniffer now monitors the latch to see if anyone has 
addressed the ASC (which sets the latch). Each time the sniffer sees 
the latch set, the sniffer clears it and resets a timer. If the latch 
stays cleared for 10 seconds, the sniffer assumes that the sound chip 
is no longer in use and turns off the sound enable line. If the sniffer 
is wrong, no problem. The next time the sound chip gets data written 
to it, sound power will come on and the sniffer resumes its latch 
monitoring. 


Diagnosti¢s 


The read ax 


The version 
firmware. The Se r€ 
test routines on its RAM and ROM and return the results. 

The soft reset command forces the PMGR to halt command 
handshaking and reset itself to the default state. Only the value of 
the real time clock is retained, all other variables are cleared to 
their default values. Normal PMGR operation resumes at the next 
60Hz interrupt. 

Consequences of misuse of these commands are severe. Direct 
manipulation of the PMGR ports can result in wasting battery power 
or even the failure of the battery. 
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PMGR COMMAND FORMAT 


Data packets consist of a command/reply byte, count byte, and 
optional data bytes. Generally, commands that have data to write are 
in the range $X0 to $X7 and commands that read data are in the range 
$X8 to $XF. Reply bytes usually match command bytes from which 
they are generated. Special confirmation replies are all in the form 
$XF. | 
CNT is the number of bytes of data being sent with the 
command. All packets contain a CNT even if no data follows the 
command/reply. Data formats vary with the command type. 


The command descriptions found below have the following 
format: 


Command Type 


command, gins thg number of dat 5 (if any) pointed 
mber of reply 


xmitbuff/recvbuff: Buffer contents of data to be read or 
written. Each command type has a unique representation of 
these data fields. Pointers to these buffers are supplied by the 
caller. | 


Power Control 


$10 - Subsystem power/clock control. Activates and 
deactivates Esprit peripheral subsystems. 


{PMGR versions D5-A3} 
CNT - 01, single data byte. 


xmitbuff: [BITMASK] 
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BITMASK - Power control data. Data is in bit mask form. 


{PMGR versions A4 and up} 
CNT - Number of data bytes in command, range 1-8. 


xmitbuff: [DO]...[D7] _ 


DO » D7 - Power control data. Data is in bit mask form. 


SCC clock 
Hard Disk power 
MODEM power 


BIT EUNCTION 
0 SWIM clock 
1 

2 

3 

4 drivers 


Thess! kK-data directly Leon the outputs of the 
power/clock contro! port of the PMGR. This eight bit port is 
tied directly to the control electronics. Bit 7 of the data byte 
determines whether the functions are to be turned on or Off. 
Those functions with their bits set to 1 will be turned on if bit 
7 is set or turned off if bit 7 is cleared. The state of these 
bits is preserved across sleep. 


Example 1 - To activate the SWIM chip for disk drive operation, 
it is necessary to turn on bit 0.of the power/clock control port 
(the SWIM control bit). Functions are turned on by setting bit 7 
of the data byte. 


BITS 76543210 
DATA 10000001 ; Turns on the SWIM chip 


BITS 76543210 
DATA 00000001 ; Turns off the SWIM chip 
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Example 2 - To disable serial communication (no modem), three 
bits must be set: SCC clock, SERIAL drivers, and -5 volts. 


BITS 76543210 . 
DATA 01010010 ; Turn off SCC, Serial, -5 


BITS 76543210 
DATA 11010010 ; Turn on SCC, Serial, -5 


Serial communication (including the modem) requires 
multiple bits to be set/cleared together. Normal serial 
communication through the external serial ports requires the 
SCC clock, the SERIAL drivers, and the -5 volt supply to turn on. 
However, they do not need to be enabled within the same 
command or in any particuja 


which enables the sound clock and sound power supply. When 
the sound manager determines that the sound chip can be turned 
off, it toggles (set true, then false) the sound clock bit. This 
Power Manager line is connected to the reset side of the latch 
and when toggled, turns off the sound clock and sound power 
supply. When reading the power status, the sound clock bit 
returns the state of the sound clock latch. 

{PMGR versions A5 and up} 
Note1a: The sound latch functions have been consolidated into 
a single command, the sound command ($90). This is the 
preferred sound control method. 


{PMGR versions A4 and up} 
Note2: When either hard disk power or SWIM clock is on, the 
PMGR also turns on a 12 volt power supply to run these devices 
(PMGR port 1, bit 0). When both devices are off, the PMGR tuns 
off this 12 volt supply. It is not necessary for the system to 
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manipulate the 12 volt supply directly, but is possible through 
use of the diagnostic commands (see section below). 


$18 - Read power/clock line status. Returns the eight bit value 
stored in the power/clock port's output register. Set bits 
(bit=1) indicate an enabled (turned on) function, cleared bits 
(bit=0) indicate an disabled (turned off) control line. 

CNT - 00, no data. 


xmitbuff : no data 


$18 - Power/clock line status reply. 
CNT - 01, no data. 


recvbuff : [PORT] 


Bit/function de ; the same ag above. Bit 7 is 


$20 - Set new Apple Desktop Bus emd (command) with optional 
data. The new cmd will go out as the next scheduled ADB 
transaction. 

CNT - Number of command data bytes, range 3-11. 


xmitbuff: [CMD] [FLAGS] [LENGTH] [DO0]...[D7] 


CMD - ADB cmd to be sent. 
FLAGS - 


BIT INDICATION 
2 Auto poll this cmd 
0 Initialization in progress (1=true) 


LENGTH - Number of bytes of ADB data (forms a Pascal 
string with DO-D7). | 
DO » D7 - ADB data to be sent with cmd (optional, 
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depending on command, 8 bytes max). 

lf the initialization bit is set, the ADB command is sent 
immediately. If the bit is cleared, the ADB command is sent on 
the next 60Hz clock. 
$28 - ADB transaction read. The status of the ADB and the data 
from the last transaction are retrieved. 
CNT - 00, no data. 
xmitbuff: no data 


$28 - ADB transaction read reply. 
CNT - Number of bytes of reply data + 3. 


recvbuff: [CMD] [STAT] [Ls 


CMD - d las 

STAT -| Status of the transa dition 

: true) 
Send/Rpceive Jerror 1=receive) 

ign (1 =true) 

device (1 =true) 

3 = ate (1=true) 

2 Auto poll this cmd (1 =true) 

1 New command received (1 =true) 

0 Initialization in progress (1=true) 


LENGTH - Number of bytes of ADB data (forms a Pascal 
string with DO-D7). 
DO»D7 - Data returned from ADB device (optional). 


The new ADB cmd is stored as the next cmd to be sent, 
then PMGR returns to continue receiving other commands. At 
the completion of 68k to PMGR I/O period, the PMGR begins its 
usual ADB transaction using the new command and data 
received earlier. If and when a reply is to be returned, the PMGR 
interrupts the 68k to initiate the command handshake. 

The 68k is interrupted only if there is reply data to 
return, no reply data and not auto-polling, an error condition, or 
an ADB device has sent a service request. 
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The auto poll bit is preserved across sleep. 


Real Time Clock 


$30 - Set real time clock. 
CNT - 04, four bytes (32 bits) of clock data. 


xmitbuff: [DO] [D1] [D2] [D3] 


DO»D3 - Hex clock data, number of seconds since Jan 
1904. DO is high byte, D3 is low byte. 


$31 - Write parameter RAM bytes 0-19. 
CNT - 20 bytes of parameter RAM. 


TART+2, range 1-34 
D(start+num-1)] 


ange 0-127. 


NUM - Number of bytes to write. 
D(start)...D(starttnum-1) - Parameter RAM to write. 


$38 - Read real time clock. 
CNT - 00, no data. 


xmitbuff: no data 


$38 - Real time clock reply. 
CNT - 04, four bytes (32 bits) of clock data. 


recvbuff: [DO] [D1] [D2] [D3] 


DO»D3 - Hex clock data, number of seconds since Jan 
1904. DO is high byte, D3 is low byte. 
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$39 - Read parameter RAM bytes 0-19. 
CNT - 00, no data. 


xmitbuff: no data 


$39 - Read parameter RAM bytes 0-19 reply. 
CNT - 20 bytes of parameter RAM. 


recvbuff: [D0]...[D19] 
DO»D19 - Parameter RAM. 


$3A - Read extended parameter RAM. 
CNT - 02, two data bytes. 


xmitbuff: [START] [NUM] 


START +S umber, range 0, 
NUM - bytes tread 
$3A - Read exe RAM repl 
CNT - Numbér of er RAM bytes , range 1-32. 


recvbuff: [D(sts aft+num-1)] 


D(start)...D(start+num-1) - Parameter RAM. 


Screen Control 


$40 - Set screen contrast. LCD screen contrast can be set to 
any of 32 values. 
CNT - 01, single byte of data. 


xmitbuff: [CONTRAST] 
CONTRAST - Hex value of desired contrast, range $00-$1F. 
The screen contrast control uses the pulse width 


modulated output of the PMGR to control the LCD screen 
voltage. The video circuitry measures the duty cycle of the line 
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and converts it into control voltage for the screen. The 
frequency and duty cycle of the output are determined by the 
values stored in two PMGR internal timers. Each timer controls 
the width of its half of the square wave output. The CONTRAST 
value is used as an index into a table of timer values that will 
result in the desired duty cycle. 


$48 - Read screen contrast. 
CNT - 00, no data. 


xmitbuff: no data 


$48- Screen contrast reply. 
CNT - 01, single data byte. 


current At, range $00-$1F. 


xmitbuff: [CONFIG] 


CONFIG - Internal modem configuration data, bit map 


format. 
BIT FUNCTION | 
2 Enable ring wakeup (1=true) 
1 Serial port A or B (1=A) 
0 Modem power (1=true) 


The function of bit 0 duplicates the power control 
functions of the power control command ($10), but will 
automatically turn on the modem and the -5 volt supply with a 
single command. Bit 1 selects which serial port the modem is 
connected to. The ring wake-up bit (bit 2), enables Esprit to be 
awakened from sleep by a telephone ring. 

Note that setting bit 0 will not enable the SCC or the 
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serial drivers, that must be done explicitly using the power 
control command ($10). This allows the user to set up the 
internal modem (perhaps through the control panel) while or 
before running a Macintosh telecommunications application. 
When the serial driver is opened by the application, which in 
turn enables the SCC, the modem connections will already be in 
place. 

The outputs from the SCC to a selected port are decoupled 
from the external serial connector and rerouted to the internal 
modem. Devices connected to this external port will remain 
undisturbed during modem accesses. 

The phone wake-up capability provides a way to remotely 
access Esprit by telephone while conserving battery power. 


xmitbuff: nojdata 


STATU podem statu ap format. 
BIT NCTION 
{PMGR versions A4 and up} 
5 Modem On/Off Hook (1=0n hook) 
4 Ring Detect State (1=true) 
3 Modem installed (1=true) 
2 Enable ring wakeup (1 =true) 
1 Serial port A or B (1=port A) 
0 Modem power (1=true) 


Battery, Charger and Temperature 


$68 - Read battery state of charge and temperature. 
CNT - 00, no data. 
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xmitbuff: no data 


$68 - Battery power/temperature reply. 
CNT - 03, three bytes of data. 


recvbuff: [STATUS] [POWER] [TEMPERATURE] 


STATUS - Battery charger status, bit map format. 


BIT EUNCTION 
{PMGR versions A7 and up} 
5 Charger connection state (1=changed) 


4 Low battery (1 =true) 
3 Dead battery ( always 0) 
2 ge counter overflow (1=true) 


icharge enpbled =true) 
r installed (Y=true) 


‘ sion formula: 
ROWER/100 +/5. volts. 
‘urrent températuye. Conversion formula: 


status. icharge-Bit is true Wheneusr the PMGR has engaged 
the hicharge circuit. Hicharging is more commonly known as 
bulk charging. Bit 2 indicates that the charging circuit is 
having trouble charging the battery and an overflow occurred in 
the counter that times the recharge cycle. If bit 3 is set the 
computer will be off, so it will never be seen true. The low 
battery bit is set when the battery voltage drops below the 
threshold value set in parameter RAM. The PMGR interrupts the 
68k once per second during the low battery condition. 


~{PMGR versions A7 and up} 

Bit 5 indicates a change in state of the charger 
connection, it either was just connected or just disconnected. 
The setting of this bit is accompanied by a single interrupt 
from the PMGR. 


The battery state of charge is rather difficult to measure 
accurately. This is due to the nature of lead-acid batteries and 
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their fluctuating power levels. Temperature, load, and other 
factors can alter the measured value by thirty percent or more. 
The PMGR does try to take into account as many of these 
factors as possible, however an error of ten percent is still 
possible. The most accurate measurements are made when 
Esprit has been in the sleep mode at least half an hour. 

If the remaining battery power falls below the LowWarn 
value in parameter ram, the PMGR will generate an interrupt to 
alert the 68k that battery power is getting low. The OS should 
request shutdown or the battery charger be connected as soon 
as is convenient. If either of these steps are not taken, and the 
power falls below the Reserve value, the PMGR will shutdown ~ 
all systems and enter the sleep state without any previous 
warning. When sufficient power is restored and the system is 
powered up, rebooting will occur as the 68k and subsystems 
will have been brought down_without preparation. The low 


interrupt to the 


Sleep 


$70 - Request CPU power shutdown (enter sleep mode). 


{PMGR versions D5-A3} 
CNT - 00, no data bytes. 


xmitbuff: no data 


{PMGR versions A4 and up} 
CNT - 04, four bytes of signature password. 


xmitbuff: [‘MATT'] 
Signature is as shown, ASCIl, all caps. If the signature is 
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not sent or garbled in any way, the command will be denied and 
the confirmation reply will not be sent. 


$AA - Sleep mode denied reply. 
CNT - 00, no data. 
recvbuff: no data . 


The sleep denied response is unique, no power manager 
command is in the form $AX. 


$7F - Enter sleep mode confirmation. 
CNT - 00, no data. 7 


recvbuff: no data 


$78 - Res 
CNT - 00, no data. 


xmitbuff: no data 


$78 - Interrupt flag register reply. 
CNT - 01, single data byte. 


recvbuff: [INTREG] 
INTREG- Interrupt flags, bit map format. 


BIT FUNCTION 
{PMGR versions A3 and up} 
3 System Reset Occurred (1=true) 


2 Temperature out of range (1=true) 
1 Battery low | (1 =true) 
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0 ADB data ready (1 =true) 


Wake Up Timer 


$80 - Set the wake up timer. 
CNT - 04, four bytes (32 bits) of time data. 


xmitbuff: [DO] [D1] [D2] [D3] 
DO»D3 - Wake up time in seconds from Jan 1904. Format 


is the same as the Real Time Clock (see Real Time Clock, 
command $30). 


_ When the real time GlOek reaches the wake up time, the 


This command disables the wake up timer if previously 
set. Only resetting the wake up timer with a new wake up time 
will enable it. 


$88 - Read wake up timer. 
CNT - 00, no data. 
xmitbuff: no data 


$88 - Wake up timer reply. 
CNT - 05, four bytes (32 bits) of time data and a flag byte. 


recvbuff: [DO] [D1] [D2] [D3] [WTflag] 
DO»D3 - Wake up time in seconds from Jan 1904. Format 
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is the same as the real time clock (see Real Time Clock, 
command $30). 


WTflag - Wake up timer enabled flag. 


BIT FUNCTION 
0 Enabled/disabled (1=enabled) 


Wake up time data is only valid if the wake up time is greater 
than the current time regardless of the state of the enable flag. 


Sound {PMGR versions A5 and up} 


(1=enabled) 


ae ible from the power 
control command ($10), however that command only sets or 
clears the sound latch reset input. The power control command 
would need two bytes of control data, one to set the latch input 
and one to clear it. The above command automatically toggles 
the latch reset input when bit 1 is set. 


$98 - Read sound control bits. 
CNT - 00, no data. 


xmitbuff: no data 


$98 - Sound control bits reply. 
CNT - 01, single data byte. 


recvbuff: [SOUND] 


SOUND - Sound control data, bit map format. 
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BIT FEUNCTION 
1 Sound latch state (1=set) 
0 Sound power (1=enabled) 


The sound latch state bit is the output of the latch and is 
the same line that goes to the sound amplifier control 
circuitry. This is not the same as the latch input bit found in 
the power control command (bit 5). The only way to read the 
state of the latch output is with the above command. 


Diagnostics 


$E0 - Write to internal PMGR memory. 
CNT - Number_of_b 


$E8 - Read PMGR internal memory. 
CNT - 03, three bytes of data. 


xmitbuff: [ADDRHI] [ADDRLO] [NUMBYTES] 
ADDRHI, ADDRLO - Start address, 16 bits, high byte first. 
NUMBYTES - Number of bytes to read, range 0-8. 
$E8 - Read PMGR internal memory reply. 
CNT - Number of bytes of data. 
recvbuff: [DO]...[D9] 


[DO]...[D9] - Internal data. 
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Using this command and the write command, bits and 
registers can be tested and modified without PMGR knowledge. 


$EA - Read PMGR firmware version number. 
CNT - 00, no data. 
xmitbuff: no data 


$EA - Firmware version data type. 
CNT - 02, single data byte. 


recvbuff: [VERSION] 


VERSION - Single, hex value signifying the version number. 


recvbuff: [RESULTS] 


RESULTS - Results of self test, in bit map form. 


BIT INDICATION 

0 ROM checksum (1=fail) 
1 RAM addressing (1 =fail) 
2 RAM data (1=fail) 


Self test may take some time to complete. Plenty of time 
should be allowed for the reply to be returned (5 milliseconds 
or more). 


$EF - PMGR soft reset. 
CNT - 00, no data. 


xmitbuff: no data 
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$EF - PMGR soft reset confirmation. 
CNT - 00, no data. 


recvbuff: no data 


This command does a soft reset of the PMGR. All settings are 
_ returned to their default state and most variables are cleared. The 
real time clock value and parameter RAM is retained. At the 
conclusion of the reply handshake, the reset takes place and the 1/O 
channel between the 68k and the PMGR is closed until the next 60Hz 
interrupt window. 
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Power Manager Command Summary 


Power Control 


$10 - Subsystem power/clock control. Activates and 
deactivates Esprit peripheral subsystems. 

$18 - Read power/clock line status. Returns the eight bit value 
stored in the power/clock port's output register. Cleared bits 
(bit=0) indicate an enabled control line, set bits (bit=1) 
indicate a disabled line. 


Apple Desktop Bus 


$20 - Set new Rasy Desktop Bus cmd command: with optional 
: I 7 heduled ADB 


KDB and the data 


Real 


$39 - Read parameter RAM bytes 0-19. 
$3A - Read arbitrary parameter RAM. 


Screen Control 
$40 - Set screen contrast. LCD screen contrast can be set to 
any of 32 values. 
$48 - Read screen contrast. 


Modem 


$50 - Set internal modem control bits. 
$58 - Read internal modem status. 
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Battery, Charger, and Temperature 


$68 - Read battery state of charge, charger status, and 
temperature. 


Sleep 


$70 - Request CPU power shutdown (enter sleep mode). 
Interrupts 

$78 - Read interrupt flag register. 
Wake Up Timer 


$80 - Set the-w 


Sound 


Diagnostics 


$E0O - Write to internal PMGR memory. 

$E8 - Read PMGR internal memory. 

$EA - Read PMGR firmware version number. 
$EC - Execute self test. 

$EF - PMGR soft reset. 
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Sleep/Idle/WakeUp and Sleep Queue 
ERS 


Michael Hanlon 
ext 4-6729 
MS 27-AJ 
Rev. 1.1A1 1/11/89 


General 


You should alreddy know what sleep is and/how it is used. If you don't, read the Power 
Manager ERS. Wnyprverstorr-writdo. If ygu ayeTiot sure whetheyor not you should be 


calling this trap should nosbe. Only spegffic ps 
be calling sleep. Mot€ likely you Waat to get into the sleg queyfe, which is described in a 
later section. 


Idle 


Esprit can be in\ : States: pdrmal, idle, pr sleep{ Normal is just that, the typical 

operational state O&th¢ j 2 
machine slows down to 1Mhz as a power saving method. The last state, sleep, is the off 
condition of the machine. The screen is blank and the CPU is not running (or even 
powered). 


The machine transitions from normal to idle when there is no activity for 15 seconds. 
Activity is defined as follows: a call to Read or Write, posting an event, execution of an 
ADB completion routine, or a call to SetCursor that changes the cursor. If any of these 
things takes place, the idle timer is reset and the wait for 15 seconds of inactivity starts 
again. If the machine is already in the idle state, these events take it out of idle and reset the 
idle timer. The idle time out is not user setable but may be disabled using the Battery desk 
accessory. 


Sleep time out criteria is exactly the same as that for idle, except that the time out is longer 
and user selectable. In addition, there are two sleep time outs. One for when the machine 
is running on the battery and one for when its connected to a charger. Sleep due to time out 
may only be disabled when the machine is connected to a charger and is set using the 
Battery desk accessory. 


The Idle code and Sleep time out code is embedded in the SystemTask routine. The Sleep 
trap is found in the PowerMgr. See the PowerMgr ERS for more information. 
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Calling Sleep 
A sleep request is called using the Sleep trap, (_Sleep or $A08A) and it takes one parameter 
in DO, as shown below. 


MOVE.L #SleepRequest, DO . ; SleepRequest = 1 
_Sleep ; SA08A 
BNE.S @didnotsleep 


Odidsleep: fsvsivacs 

A sleep request is only that, a request. If the system determines that there are one or more 
reasons why the system should not go to sleep, the request is denied and the EQ condition 
code is set not equal. 


Entities that request sleep: sleep time out. 


A sleep dem ane is called using the Sleep trap, (_Sleep or $A08A) and it takes one 


A sleep demand is conditio e on having fie servers mounted. 4 anyAerver is mounted, 
an alert will appear askigg thesrSer tNhey still\want to sleep. Iffhey s#y no the trap returns 
without going to sleep. ye user chopses to slkep anyway th€ servgfs are unmounted and 
AppleTalk is closed. 


A sleep now is called using the Sleep trap, (_Sleep or $A08A) and it takes one parameter in 
DO, as shown below. 


MOVE. L #SleepNow, DO ; SleepNow = 6 
_Sleep ; SAQ8A 


A sleep now is unconditional, Esprit will go to sleep even if some processes may be 
harmed. Any servers are unmounted and AppleTalk is closed. Sleep demand is generally 
used to power off the machine when a critical low power condition arises. 

Entities that demand sleep: low power alert. 


The Sleep trap may not be called at interrupt level. 


Th | ueue 


As part of its preparation for sleep, the sleep trap goes through a queue of procedures, 
executing each one and informing the procedure of its intentions. The sleep trap may be 
trying to do any of three things: request permission for sleep, alert of a sleep, or 
inform the procedure that wakeup is underway. 
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Entities that wish to be given cpu time before and/or after sleep must place themselves in 
this queue. The sleep queue is a standard OS queue. Shown below is the sleep queue 
record structure. 


TYPE SleepQRec = RECORD 


SleepqLink: QElemPtr; 

SleepqType: Integer; {type = 16} 

SleepqProc: ProcPtr; {Pointer to sleep routine} 
SleepqFlags: Integer; 


END 


The sqFlags field contains two flags to be set by the sleep routine before installing its record into 
the queue. 


Fla Bit Indication 


Call procedure at sleep 
Call procedure at wake up 


these bits as desired. 


MOVE #MyOF lags, SleepQF lags (A0) ; Fill flag field 

MOVE #sQType, SleepqType (AQ) ; Fill type field 

LEA MySleepProc,Al ; Load pointer to my handler 
MOVE.L Al, SleepgProc (A0) ; Fill proc field 

MOVE.L PmgrBase, Al ; Lomem base of Pmgr locals 
LEA SleepQHdr (Al) , Al ; Pointer to queue header 
_Enqueue ; Add to queue 


To remove a record from the queue: 


Load AO with pointer.to the record 
Load Al with pointer to sleep queue header 
Call dequeue 


Example 
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MOVE.L MyRec (A2) ,A0 Pointer to my record 


ve 


MOVE .L PmgrBase, Al ; Lomem base of Pmgr locals 
LEA SleepQHdr (Al) ,Al1 ; Pointer to queue header 
_Dequeue ; Add to queue 


Procedures in the queue may be called with any of values in DO. These values indicate the 
type of call underway. 


1 = Sleep request 


2 = Sleep demand 
3 = Wake up 


Sleep Queue Calls 


A complete sleep call to a sleep queue ae consists of a single sleep demand call ora 
sleep request call followed _b d all. 


For sleep request, each] queue entry gets qalled with DO containing the JleepRequest 
parameter. Once all thejentrgesarecatted“and none/of txém hg’sleex request, each 
entry is called again, this timp with-the-SleepDemané fi soon follow 


If any one of the entries|denies fit sie aled tha 
far get a SleepWakeUp call jhdicating \hat the sleep request is Peing yborted. It is probably 
best for entries not to actyally do the sldep preparation until fhe sleep demand call is made, 
but this may not be tru¢‘in all Sases. SlgepRequ¢st is used ith all entries to see if 
sleep a OK and to indifate to qntries tAat they ghould lock Hut any Activity that might make 
it not OK. 


To OK the sleep request, the sleep queue entry procedure must clear DO. To deny sleep, 
DO must be returned nonzero. Denying sleep is not a good idea. 


The SleepDemand call cannot be denied. All entries in the sleep queue must do the best 
they can to prepare for a sleep demand. 


Since the _Sleep trap is not called at interrupt, the procedure can do quite a bit to make 
sleep possible (even use the memory manager!). In some cases it may be desirable to ask 
the user for an OK or to alert the user of some problems that may occur, however this is 
not recommended. It may be possible for many sleep queue procedures to be called and if 
they all put up a dialog, things can get confusing. 


The SleepWakeUp call is made to each sleep queue entry upon wake up. This call cannot 
be denied. 


Remember, choosy programs choose sleep. 
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PowerMor ERS 


Michael Hanlon 
ext 4-6729 
MS 27-AJ 
Rev. 1.0A1 1/11/89 


Introduction 


This document describes of routines found in the file "Powermgr.a”, a file 
unique to the Es . The routfnes found in this file include the _PmgrOp 
trap, the communication routines to the Powgr Mana [GR), the power 
manager interrupt digpa amt pt hgndloxs; Oweptime out routine, the 
internal hard disk time ine. the _Sleen uf oft ake up routines, and 


PmgrOp 
Access to the mi ffom the power mangger processor is provided in a 
single OS trap. \ géss to all PMGR conimands using the calling 
convention described-he 

Entry: AO = Pointer to PMGR parameter block 

Exit: DO = Result code (integer) 


Trap Macro: _PmgrOp 


PmegrPBlock = 
Record 
pmgrCmd: INTEGER; 
pmegrCnt: INTEGER; 
pmgrXptr: ptr; 
pmgrRpt: ptr; 


° 
> 


Upon entry, pmgrCmd is the PMGR command to be executed and uniquely 
describes the data pointed to by pmgrXptr. The command is replaced by the reply upon 
exit. pmgrCnt is the number of bytes of data to send (if any) pointed to by pmgrXptr. 
Upon exit, pmgrcnt is the number of data bytes received (if any) pointed to by pmgrRptr. 
The pointers pmgrXptr and pmgrRpt, are the data transmit buffer and the data receive 
buffer pointers, respectively. The caller supplies the parameter block and storage for 
pmegrXptr and pmgrRptr to point to. 
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Result codes 


noErr 0 

pmBusyErr -13000 ; Pmgr stuck busy 

pmReplyTOErr ~  =13001 ; Timed out waiting to begin reply handshake 
pmSendStartErr -13002 ; Pmgr did not start handshake 
pmSendEndErr -13003 ; During send, pmgr did not finish handshake 
pmRecvStartErr -13004 ; During receive, pmgr did not start handshake 


pmRecvEndErr -13005 ; During receive, pmgr did not finish handshake 


The _PmgrOp trap disables interrupts for up to 2 milliseconds for handshaking 
data. For a complete description of the Power Manager interface and command set, see the 
Power Manager ERS. 


Interrupt Dispatcher 


VIA input CB2 provides ape Sees to the ites tees fies interrupt dispatcher 
first reads the interrupt r¢giste [GR then sels etwee ee possible Power 


Battery Interrupt 
The PMGR will send a\battery (inte ther the baftery power has fallen below the 
warning threshold, or when = Cie is comnected or di connect d. The charger state 


change interrupt occurs onct pafige. The low pé t occurs once per 
second for as long as the battery | power is below the warning threshold and the charger is 
disconnected. The battery interrupt has second priority. 


If the charger is connected at the time of the interrupt, then the interrupt is due to a state 
change of the charger connection. and control is passed to the time outs updating routine 
(see below). If no charger is connected at the time of this interrupt then the cause is due to 
a low power condition. The interrupt routine determines what level the battery is and 
decides on what warning to post to the user. The user will get one warning at the onset of 
low power, one at three quarters of reserve power remaining, one at half or reserve power 
and one at one quarter reserve power remaining. The warnings consist of an alert box and 
a small flashing battery icon. The text in the alerts apprises the user of the low power 
condition and what action to take. Each succeeding message is stronger than the previous 
one. The last warning tells the user that the machine is going to sleep shortly. The icon 
flashing remains until the low power condition changes (by connecting the charger). The 
small battery icon and the text within the alert boxes are stored as resources in the system 
file. 


SICN -2000 ; small battery icon 

STR -2000 ; first low power alert 

STR -2001 ; second low power alert 
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STR - -2002 : final low power alert 
STR -2003 ; shutdown eminent warning 


The Background Notification Manager is used to provide the low power alerts. 


If the machine is sent to sleep during a low power condition then it must be recharged 
before it will wake up again. 


Tim Updatin 


There are two sets of time outs that the system uses to control spinning down the internal 
hard disk and going to sleep, one set for when the machine is running on the battery and 
one set for when its connected to the charger. The time out update routine reads the correct 
values from parameter RAM and loads the time out counters. 


These values are set by using the Battery Desk Accessory and saved in parameter RAM. 
When any value is changed by the Battery DA, it sets a flag in memory. This flag is used 
by the Battery Monitor mas below) routine to know when the values have changed and to 
call the time out ypds dne-+to-tad jthe ne pte 


The deca mogpftor checks the i the sound power system each 
TOF eT ten seconds of no accesses to the 
ASC, the battery monitor system turns off the sound power. 


After the sound system is checked, the hard disk and sleep time outs get attention. First the 
hard disk time out is compared against the time of the last disk access. If the time out has 
been reached then the disk spin down procedure is called. Next the sleep time out is 
checked against the time of the last activity. When this inactivity time out is reached a call 
is made for a sleep request. 


Sleep and WakeUp 


The Sleep trap is call made by the system to send the machine to sleep. This trap does a 
number of things to prepare the system for sleep. First it saves all the 68000 registers on 
the stack. Next it calls the sleep queue routine to allow other entities to prepare for sleep. If 
traversing the sleep queue results in sleep being denied then the 68000 registers are restored 
and the sleep trap returns. 


Sleep preparation continues with saving the reset vector, the contents of the VIA and ASC 
control registers, and RAM configuration register on the stack followed by saving the stack 
pointer in memory. Next the wake up procedure pointer is moved into A3 and the call to the 
PMGER to go to sleep is made. In the final milliseconds after the call to the PMGR and 


PowerMgr ERS Rev 1.0A1 3 1/15/89. 
Apple Computer Inc. Confidential 


before sleep actually takes place, the wake up procedure is loaded from A3 and the sleep 
constant is put into the warm start flag. 


Upon wake up the process is reversed and the system is restored. The default wake up 
procedure get the stack pointer from memory and restores the RAM configuration register, 
the ASC and VIA, and the reset vector. Next the SCSI chip is reinitialized and the current 
time is read from the PMGR. The sleep queue is traversed again, this time as a wake up 
queue. Finally the 68000 registers are restored and the trap returns to the caller. 


Sleep Queue 


This routine traverses the entries in the sleep queue differently depending on what type of 
call it is, sleep request, sleep demand, or wake up. 


time the sleep demand parameter is procedures. Once all the procedures have 
been executed using both ret a sleep granted result (DO=0) 

In the case of sleep demand an¢ queue is wit the Appropriate 
parameter. Procedures carjnot demand or wg € royfine always 
returns a no error result. Spe t for more details onAsing fhe trap and 
queue. 

Power Off 

The shutdown manager ca we whe as its las¥act. This simple routine delays 


one second to allow for any f to eject T ép and. Immediately 
following the sleep call is a jump to the start of the ROM, effectively resetting the machine 
upon wake up. 
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Cobra _ II/Spin 


ROM Software ERS 
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Overview 


The Spin and Cobra II are MC60830 based machines that are software 
compatible to Landru, Cobra and Fafnir. The hardware design focuses around a pair 
of custom VLSI parts, the Memory Decode Unit (MDU) and Ram-Based Video controller 
(RBV) from which a family of CPUs can be developed. The MDU is designed to 
support 20 MHz and 25 Mhz MC68030. The RBV is designed to provide on board 
video support for multiple video monitors. The software for both Spin and 
Cobra II are almost identical, The ROM is based on the integrated sources of the 
Macintosh II ROM, overpatches for Landru, Cobra and Fafnir, and system 
patches for all the bug fixes that are relevant. In addition to patches, several 
major features are added to make these machines more competitive at the time 
of introduction. This document describes features that must be included in the 
ROM plus the necessary software changes for the MDU/RBV chip set. Other 
features that may be included in the ROM will be added to this specification as 
they become available. 


Here is a brief summary of all,the major changes required for the ROM: 


1) Interrept handler changes, the /RBV p the functions of 
the se¢ond iJe Inteffaces acintosh II, so 
the se¢ond nated. 

2) New handle multipfé vidgo monitors will reside 
in the [ma \f the configuyAtion 

3) Start es to support MDY%. Th¢ MDU split the memory 
bankd into two 64/Mbyte Jegments gnd thef video screen buffer resides 


4) New memo 


y“sienry routine to suppo 
mother board. 


up to 128 Mbyte of RAM on the 
5) Memory manager changes to support real 32-bit addressing. This will 
cause non 32-bit clean applications incompatible 


6) Remote booting support requires changes to the Start Manager, 
Appletalk driver and the file system. 


There will be a new System Disk release to support Spin and Cobra II. The 
features of the new System Disk are described in the System Disk ERS. 
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2.0 Start Manager 


2.1 MDU Support 


Basically, the MDU memory controller is responsible for decoding all the 
memory accesses to RAM, ROM and I/O space. The RAM address space is divided 
into two 64 Mbyte Banks. Address space for Bank A is from $00000000 to 
$03FFFFFF and Bank B is from $04000000 to $07FFFFFF. Extra RAM expansion 
space is from $08000000 to $40000000. ROM address space is from $40000000 to 
$4FFFFFFF. I/O address space is from $50000000 to $5FFFFFFF. NuBus address 
space is from $60000000 to $FFFFFFFF. Please refer to figure 1 for the memory 
map and figure 2 for the I/O map. For more details of the MDU, please refer to 
the MDU User Manual by Michael Dhuey. 


2.1.1 Ram Sizing 


contiguous to Bank A, 
and set up the addres ; 
non-contiguous physical ad will map to contiguous logical address 
space. 


2.1.3 Address Convertion Support 


Since the logical address for most RAM address space is not the same as its 
physical address, some low level drivers which rely on the physical address 
will have to convert the logical address to physical address. A new trap 
_GetPhysical will be implemented to provide the address convertion. The 
logical address is passed to the trap through register AQ, the physcial address is 
returned through register AO. 


2.2 RBV Support 

The RBV is an on board RAM based video controller which provides support for 
Macintosh ll-style video on.a number of different monitors as an integral part of ail 
Cobra-based CPUs. Unlike the current set of NuBus video cards which focus on high 
functionality and maximum performance, the Cobra video hardware provides the most 
useful subset of video functionality at extremely low dollar cost, but at some cost to 


Apple Computer Confidential | Page 4 


overall CPU performance. Users who require advanced video features may easily add 
them via NuBus cards (if their hardware configuration includes NuBus). The 
following video monitors are supported by the RBV: 


1) 9-inch Mac SE monitor (512 x 342) 

2) 12-inch modified Apple II GS RGB monitor (512 x 384) 
3) 12-inch Mac II B/W or 13-inch RGB monitor (640 x 480) 
4) 15-inch vertical-format monitor (640 x 870) 


For the first three monitors, the RBV can support 1, 2, 4 & 8 bits per pixel while 
the 15-inch monitor, it can only support 1, 2 & 4 bits per pixel. For reasons, see 
section on Issues on MDU & RBV. 


2.2.1 Video Address Mapping 


In order to simplify the design of the RBV, the screen display buffer starts at 
physical address $00000000 since the MC68030 has a built-in MMU which can 
map the screen buffer to some other logical address. New code is required to 
find out what, if any, monitor is attached to the video port and then find out 

how big the display buffer is required. The size of the screen buffer depends 
on the resolutio tte POPHtSt ii te ar 


in parameter RAM and 'scrn’ resource 0 
screen buffer is] obtp#réd, the~bsyffer is 


2.2.2 RBV 


2.2.2.1 Overview 


This section describes the video software subsystem for the the Cobra II CPU ROMset 
which will be used for Spin. The major component of the Cobra video software is a Mac- 
OS device driver which can identify the desired hardware and monitor configuration and 
control the RBV accordingly. In addition, there is also a configuration data component 
that identifies the characteristics of each video mode to Color QuickDraw, and a number 
of new driver routines that are associated with ancilliary hardware functions of the Spin 
hardware. 


The implementation of the Spin hardware has a number of implications on areas of 
system software both within and outside of the Cobra ROMs proper. A number of these 
issues are discussed at the end of this document. 


2.2.2.2Video Driver Implementation 


The RBV and Color LookUp Table (CLUT) chip embody a fully functional video hardware 
system that supports a number of video modes in a highly integrated manner. Unlike 
NuBus video cards which each have their own configuration ROM, or Fafnir which has a 
special video ROM for it's integral video hardware, the Cobra video driver will be 


Apple Computer. Confidential | Page 5 


integrated into the CPU ROM as a "slot-zero" motherboard device. As such, the video 
driver must anticipate all possible hardware configurations, in many cases before the 
actual hardware is built. Although the programming of the RBV hardware is 
considerably simpler than the current crop of video cards, a large part of the code in the 
Cobra driver will be devoted to identifying and appropriately supporting the particular 
hardware configuration that it is installed in. 


The RBV supports the following video modes: 


1) 640*480 pixels. This supports the existing Macintosh II! Hi-Resolution RGB and 
Monochrome displays. 


2) 512*342 pixels. This is a mode which generates video compatible with Mac SE 
or Fafnir displays for use in compact machines. Unlike these machines, however, the 
RBV can generate color displays at this resolution if the CPU is equipped with an 
appropriate CLUT chip. 


3) 512°384 pixels. This is a new video mode designed for medium resolution 
monitors running at 60Hz vertical refresh, non-interlaced. This class of display 
provides reasonable color capability at considerable lower cost than the 640*480 Hi- 
Res displays. 


4) 640*870 pixels. This mode is ji 
display. 


systems is that the Cobre 
buffer. Rather, the RBVj 
main dynamic RAM ba 


de z - 
percentage of memory bandwidth lost to video accesses for a 20MHz 68030: 


512*342 512*384 640*480 640*870 

9-inch_ SE ll-GS RGB 13-inch Mac _ Il 15-inch 
1 bit/pixel 4% 5% 8% 16% 
2 bits/pixel 8% 9% 16% 33% 
4 bits/pixel 17% 19% 32% 66% 
8 bits/pixel 33% 37% 64% n.a. 


Table 1. Average loss in bandwidth for 20 Mhz MC68030 with different monitors 


The amount of cycles required to support a given video configuration is constant, so the 
available screen depths vary according to the master CPU clock of the processor— on a 
16MHz processor (where fewer total memory cycles are available), most of the modes 
cannot support 8-bit screen depth. This means that additional code and configuration 
descriptions must be developed for each video mode depending on processor speed. The 
video driver itself does not contain timing-dependent code and will not require any 
special code related to processor speed. 


To simplify the hardware design, the RBV's frame buffer always begins at physical 
location $00000000 in the CPU's address space. After startup, the 68030's MMU is 
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used to map the frame buffer into some other convenient address space. Color QuickDraw 
can arbitrarily draw in to pixmaps located anywhere in the processor address space, so 
this should not be a problem. To prevent screen glitches when performing a warm start 
(doing a restart from the Finder for instance), the frame buffer memory should not be 
cleared or modified. 


It is possible that the user may decide not to use the embedded video hardware, opting to 
use a NuBus video card instead. In these circumstances, the video memory accesses can 
be disabled, improving the performance of the CPU. To support this feature, the video 
driver includes a new disable control call (and a related status call that reports whether 
the internal hardware is active or inactive). The Monitors cdev will be revised to allow 
video cards to be selectively activated or deactivated. Part of the deactivation process 
will be the issuance of this new control call to supress video refresh. The video software 
itself will not be responsible for notifying the other parts of the system that the 
processor execution speed has changed, however, it may call the appropriate system 
notification routine if appropriate. 


One item yet undecided is the mechanism used to determine the amount of frame buffer 
memory to be allocated at startup for frame buffer displays. Currently, video cards 
remember the last used bit-depth in pRAM to allow the Primarylnit code to run in the 


: aril. a fixed, maximum sized buffer 
could always be Bllocated, and, in lower scrge some of this memory will just go 


to waste. This p 


above. Althoughjit g BS spe Dport on-the-fly speed 
changes, it seems unfegserabteta force the y em when changing 
screen depth (especi Bater scr ch a substantial speed 
penalty). 


has the cappbility tojsense the onitor currently attached to 
pecial ljnes uniqpiely encodgd for egch display. The hardware can 
nectedj however, the selection of 


The Spin hardwage 


disconnect one typé™e itor-ard reconnect to &differest display without having to 
reboot the system. This mode of use will probably not be possible due to a number of 
restrictions in the high-level toolbox routines. Although changing monitors on-the-fly 
will result in a stable video raster, it will not result in a viewable screen. 


This machine does not require a special A/UX video driver. All 68030 machines will 
run with A/UX 1.1 or later and this system uses the MacOS version of the driver. Since 
the special A/UX driver is used only by A/UX 1.0, it need not be present in the Cobra 
system. 


2.2.2.3 Configuration ROM Implementation 


The other main component of the video software is the configuration ROM information 
that informs Color QuickDraw of the size and shape of the video display device. The Spin 
video sRsrc information will be included in the main CPU ROMs as part of the "slot- 
zero" information, or information that describes motherboard devices. Generally, this 
does not involve any substantial changes to the content of the Slot Manager information, 
however, it may involve some modifications to the Primarylnit code to appropriately 
determine base address, slot number and other information. Slot-zero support will be 
new in the Cobra ROMset. 
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Currently, all possible video mode sRsrc descriptions must be present and unmodifyable. 
In the case of the Cobra video hardware, this would involve separate sRsrc lists for each 
permutation of video display timing, processor timing, and memory configuration. 
Under this model, the particular hardware/monitor configuration is determined at 
Primarylnit, and all others are deleted. As an alternative, the Cobra Slot Manager may 
allow the construction of RAM-based sRsrc lists at Primaryinit time. If this feature is 
available, it may be preferable to the current implementation. 


Outside of slot-zero considerations, the Cobra configuration ROM will not take advantage 
of any of the new video features such as display families. 


2.2.3 RBV_ registers 


Other than supporting on board video, the RBV has eight 8-bit registers whose 
functions include slot interrupts, second VIA, chip test and monitor 
parameters. The following are the bit assignments of the eight registers. For a 
more complete description, please refer to the RBV design document by Brian 
Howard. 


General Bit 
Function No, 
VIA2 Data 
| 0 
VIA2 1 1 
Data 1 2 
Register | 3 
B 1 4 
1 5 
(PBO-7) | 6 eTiTa peaker, 0 = External audio jack in use 
| 7 1 = Expansion output high, 0 = Exp. output low 
Future Expansion Address: $5002 6001 
Associated Reg. Bit is 
General Bit Signal Pin is _—_Read/ 
Function No, Name In- or Output Write Description of Bit 
0-7 Reserved (no pins) Read Always read 0 
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Slot Interrupts 


General Bit 
Function No. Name 
| 0 SLOT1.IRQ* 
| 1 SLOT2.IRQ* 
1 2 SLOT3.IRQ* 
NuBus | 3 SLOT4.IRQ* 
Slot 1 4 SLOTS.IRQ* 
Interrupts | 5 SLOT6.IRQ* 
|! 6 SLOTOIRQ* 
| 
17 Reserved 


Function No, Name 


Address: $5002 6002 


Associated Reg.Bit is 
Signal Pin is _Read/ 
In- or Output Write Description of Bit 
Input Read 0 = NuBus Slot 1 interrupt 
Input Read 0 = NuBus Slot 2 interrupt 
Input Read 0 = NuBus Slot 3 interrupt 
Input Read 0 = NuBus Slot 4 interrupt 
Input Read 0 = NuBus Slot 5 interrupt 
Input Read 0 = NuBus Slot 6 interrupt 
(Input) Read 0 = Internal video blanking interrupt (when RBV 
video is tri-stated, 0 = external Slot 0 interrupt) 
(no pin) Read Always reads 0 . 
Address: $5002 6003 
Associated Reg. Bit is 
Signal Pin is Read/ 
In-or Output Write Description of Bit 


Bits | 0 COLORS! (sb) | 
Per | 1  COLORS2 
Pixel | 2  COLORS3 (msb)_! 
Read | 3  RD.MONI (sb) | 
Monitor | 4 RD.MON2 | 
Type | 5  RD.MON3 (msb)_| 
Video | 6  VID.OFF 

Control | 7 VID.3ST 
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(Write 1 to clear) 
(Write 1 to clear) 
(Write 1 to clear) 
(Write 1 to clear) 


000=1Bit, O01 =2 Bit 
010=4 Bit, O11 =8 Bit 
1xx = Reserved (these values cannot be written or read) 


000, 011, 100 = Reserved; x01 = 15" portrait monitor 
010 = Mod'd II-GS monitor; 110 = Mac II 12/13" mon's 
111 = No external monitor ( = 9" built-in monitor, in SE) 


0 = Normal, 1 = Video Off (CPU gets all RAM cycles) 
0= Normal, 1 = All video outputs tri-stated 
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Chip Test Address: $5002 6011 


General Bit Read/ 
Function No, Name Write Description of Bit _ 
0 C60.ILGL R/W 0 = Normal, 1 = C60 clock runs 128 x normal. If 
TEST.RES (bit 7) = 1, vertical counters 
= 7 also set to all 1's (illegal state) 
Test 1 1 V.SPEED1 (isb) | R/W 00 = Normal (vertical counters increment +1 every line) 
Speed |. 2 V.SPEED2 (msb)_| R/W 10 = Medium (+6 every line), 01 = Fast (+1 every 16 dot: 
11 = Very Fast (+6 every 16 dots) 
3 HNDSHKS.3-ST R/W 0 = Normal, 1 = VDATA.REQ* & VADRS.RES* tri-stat 
4  JOCLKS.3-ST R/W 0 = Normal, 1 = C16M's, C8M, and C3.7M tri-stated 
5  C30M.ALWYS R/W 0 = Normal, 1 = 30.24 MHz clock for all monitors 
6  STOP.DTCLK R/W 0=Normal, 1 = Dot clock halted 
7  TEST.RES R/W 0 = Normal, 1 = Reset video counters (also, see bit 0); 
read latched video data from $5002 600(0-3) 
Slot Interrupt Enables Address: $5002 6012 
General Bit Read/ 
Function No, Name Write Description of Bit 
1 0 Legere IRQ*.EN R 1 = NuBus Slot 1 interrupt enabled 
| ; l= = NuBus Slot 2 interrupt ¢ gnabled 
NuBus | 2 
Slot | 3 
Interrupt | 4 
Enables | 5 
1 6 
| 7 


General Bit 
Function No, 
1! 0 SCSIDRQ.EN R/W 1 = SCSI DRQ interrupt enabled 
| ANY.SLOT*.EN R/W 1 = ANY.SLOT™ interrupt enabled 
VIA2 | 2 EXP.IRQ*.EN R/W 1 = Expansion interrupt enabled 
Interrupt | 3 SCSLIRQ.EN R/W 1 = SCSI IRQ interrupt enabled 
Enables | 4 . SND.IRQ*.EN R/W 1 = Sound Chip interrupt enabled 
| 5 Reserved Read Always reads 0 
| 6 Reserved Read Always reads 0 
l_7 Set/Clear | R/W On Reads: Always reads 1 


On Writes: 1 = 1-bits in bits 0-6 write 1's; 
0 = 1-bits in bits 0-6 write 0's 


2.2.4 Interrupt changes 


In replacing the second VIA, the RBV devotes 5 registers to provide the same 
functions, and they are WIA2 Data, Slot Interrupts, Interrupt Flags, Slot 
Interrupt Enables and Interrupt Flag Enables. The initialization code in Start 
Manager for the interrupt vectors and the interrupt handler routines have to 
be modified to use the new registers. 
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The two timers of the second VIA are not used by any current routines in the 
Macintosh II and will not be supported. 
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Map on Power-Up Normal Map 
(before first access to (after first access to 


$4000 0000 - $4FFF FFFF) $4000 0000 - $4FFF FFFF) 


$ 10000 0000 


$ F100 0000 


$ F000 0000 No Device Assigned 


$ C000 0000 


No Device Assigned 


$ 9000 0000 


: $ 6000 0000 
Expansion I/O Space Expansion I/O Space 
$ 5200 0000 1 eee eee 


$ 5000 0000 


Expansion ROM Space Expansion ROM Space 


sion RAM Space 


$ 0800 0000 
$ 0500 0000 
$ 0440 0000 


$ 0410 0000 


$ 0400 0000 
$ 0200 0000 


0100 0000 


0040 0000 


0010 0000 


0008 0000 
0000 0000 


Figure 1. Physical Memory Map 


PRA Ff Hf “A 
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Complete 
Memory 
Map 


Figure 2. |/O Memory Map 
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provides 
DSACKO 


~ chip 


MDU 

provides 
chip 

select 
only 


MDU 
provides 
DSACKO 


MDU 


MDU 
provides 


“select 
~only 


MDU 
provides 
DSACKG. 


Expansion I/O Space 


Expansion I/O Space 


Reserved for Apple 


$ 6000 0000 
$ 5900 0000 
$ 5800 0000 
$ 5200 0000 
$ 5100 0000 
$ 5004 0000 
$ 5003 0000 
$ 5002 E000 
$ 5002 C000 
$ 5002 A000 
$ 5002 8000 
$ 5002 6000 
$ 5002 4000 
$ 5002 2000 
$ 5002 0000 
$ 5001 E000 
$ 5001 C000 


$ 5001 A000 


_ $5001 8000 


$ 5001 6000 
$ 5001 4000 
$ 5001 2000 
$ 5001 0000 


$ 5000 E000 
$ 5000 C000 
$ 5000 A000 
$ 5000 8000 
$ 5000 6000 


$ 5000 4000 
$ 5000 2000 


$ 5000 0000 
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3.0 32-Bit Addressing Support 


In order to fully utilize the capability of the MC68030 and extend the Macintosh 
operating system to the future, 32-bit addressing is the first step that has to be 
taken. Applications that rely on the internal data structure of the 24-bit 
Macintosh operating system would have compatibility problems with the 32- 
bit addressing mode. Since all third party developers are seeded with an early 
32-bit Macintosh II ROM, applications that have compatibility problem should 
already been revised when Spin & Cobra II are introduced. 


3.1 Overall ROM Clean Up 


The primary reason the Macintosh Operating System runs in 24-bit mode is 
that the high byte of a master pomter ig_used as a Hee pyle oy the Memory 
Manager. Some third 2 Abend 


Since 32 bit addressing wilfimtromuce a big compatibility problem for most 
existing applications and also our current System Disk 6.0.x. The 32 bit feature 
of the Memory Manager will not be turned on until Big Bang System Disk is 
introduced. On boot up, before any heap zone is established, the Startup code is 
going to check a byte in Parameter RAM to check if it should turn on 32 bit 
addressing mode. If the 32 bit addressing mode flag is on, the Memory 
Manager will generate all heap zone for 32 bit addressing, otherwise it will be 
set up for 24 bit addressing. The 32 bit addressing mode flag is also copied into 
low memory, the Memory Manager checks the flag in low memory’ when it 
manipulates any data structures that are different between 24 bit and 32 bit 
addressing. 


System Disk 6.0.x will support 24 bit addressing, while Big Bang System Disk 
will support 32 bit addressing. When user switch between 6.0.x and Big Bang, 
the Startup Manager checks a new resource “adrm" on the System file, if the 
value of the resource does not match the value of the Parameter RAM, the 
startup code will update the Parameter RAM will the new value and then it will 
reboot. The reason for the reboot is that the system heap that had already 
been set up is not right for the expected addressing mode. The checking of 
the “adrm" resource will happen as soon as the Startup process can access the 
System file so when the reboot happens, it will be before the "Welcome to 
Macintosh" message. The reboot only happens on the very first time the user 
switch from one System Disk to another. 
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3.3 Memory Manager Changes 


In order to support both 24 bit addressing and 32 bit addressing, the memory 
manager has to handle both data structures at the same time. The low memory 
32 bit address flag will tell the Memory Manager how to manipulate the 
memory block header. There will be no changes to the memory block header 
for 24 bit addressing. 


3.3.1 32 Bit Memory Block Header Format 

In32-bit addressing, all addresses are 32 bits long, so the high byte of the 
master pointer can no longer be used as a flag byte. One solution is to relocate 
it to the block header. 


The current memory block header is eight bytes long as shown in figure 3. 


The physical Ylock sike field/is 3 bytes long eans a zone can be no 
bigger than 16\ Mbyte the past but it will be a 
severe limitation\for i qd expand the physical 

block field size to 2™bytes—err’ also add a coupte~bytes to the block header, one 
of which is for the flag byte from the master pointer. The new block header is 
twelve bytes long as shown in figure 4. Tag byte 1 (see figure 5) is the same as 
the old tag byte minus the size correction field. Size correction field now takes 
up a whole byte. Tag byte 2 (see figure 6) is what used to be the master pointer 


flag byte. 


Figure 4. New Memory Block Header 
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-not used 
00:free block 
01: nonrelocatable block 


10: relocatable block 


Figure 5. Tag byte 1 


Figure 6. Tag byte 2 


All the routines that manipulates the memory block header plus the master 
pointer flag byte have to be modified for the new data structure. 
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4.0 Other Features 


4.1 Script Manager 


Script Manager is an extension to the Toolbox to support multiple writing 
scripts and it is part of the Toolbox since Macintosh SE and Macintosh II 
introduction. Although it is part of the Toolbox, it is installed into the system 
RAM space during system bootup time. For this ROM, Script Manager will be 
rolled into the ROM source and be part of the ROM code. A few extra resources 
will be required by the System Disk for the keyboard and the Key Caps DA to 
function probably and they should be covered by the System Disk ERS. 


4.2 Remote Booting 


upgrade. For compte details oINRemote Booting, Please/refer to the Remote 
Booting ERS. 


A new asynchrono mMfager will be ed-—into the Cobra II and Spin 
ROM, the new SCSI Maiager will allow a more efficient way of handling data 
transfer between the system and other SCSI devices. Please refer to the Async 
SCSI Manager ERS for details. 


4.4 32-bit Color QuickDraw 


Color QuickDraw will be extended to support 32 bit per pixel output to Nubus 
video cards. It will be able to access more than 1 Mbyte of RAM on those cards. 
Please refer to the 32-bit Color QuickDraw ERS for details. 


4.5 Notification Manager 


Notification Manager provides a set of calls for applications to generate alerts 
or warnings even if they are the background tasks under MultiFinder. 
Notification Manager is a system patch on System Disk 6.0, it will be rolled into 
ROM for both Cobra II and Spin. Please refer to the Notification Manager ERS 
for details. 
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Jaws ERS 


Gary Davidian 
ext. 4-4510 
MS 27-AJ 
Rev. 0.0 D1 1/18/89 


What i ws project? 


The Jaws project is a proposed universal Macintosh CPU ROM. There are at least two families of 
Jaws ROMs envisioned. Jaws 16 is a universal ROM for the Mac Plus, Mac SE, and possibly Esprit 
CPUs and possibly other future 68000 based 16 bit architectures. Jaws 32 is a universal ROM for the 
Mac II, Mac IIx, Mac SE/30, Cobra I, Cobra II, 4 Square, Spin, and possibly F19 68020/030 based 
32 bit architectures. 


© used on seve iffe hardware configurations. When 


machine it is runnifg on "and configurf itself/to use those features. Wsing a single ROM across 


several products has|sevéfar advantages. Softwpre pfaintainability é primary motivation, because 
one patch file on the|systemp-dist-eeuld apply to*s e/may also be manufacturing cost 
savings by have higl umes Son a sind e niversal ROM st, ingfead of lower volumes of several 
unique ROM sets. 


oject is thafby haying the ROM determine the hardware 
features that are prfsent, N could spipport configuratiogs that we may want to build in the future (eg. 

Jaws 16 would include SuperDriyé ae for the Mgt SE, byt if we were to add a SWIM chip to the 
Mac Plus (or some he eTTG e ROM wofld detect that feature, and automatically support 
it). 


An additional goal of the Jaws project as time permits, is to gather performance statistics of the current 
ROM code, and optimize the new ROM code as much as possible. I have already optimized the trap 
dispatcher, and block move routine. 


If we decide to do a field ROM upgrade such as a 32 bit clean ROM for the Mac II, or to support a 
future system software release (eg Big Bang), we could produce just two new ROMs (Jaws 16, and 
Jaws 32) to retrofit all of the machines that we produced from the Mac Plus on. 


What the Jaws project isn't. 


While there are a number of new system features that are being introduced with the Jaws ROM (32 bit 
clean memory manager, on board video drivers, IOP based drivers, SCSI DMA, remote booting, 
etc.), the implementation of those features is outside the scope of the Jaws project, although the code 
to configure those features (if they are hardware dependent) is within the Jaws project. 
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Famous ROMs in Macintosh History 


The concept of a universal ROM is not new to the Macintosh. As described below, all of the ROMs 
released to date have had some sort of universal features. 


The very first Macintosh 64K ROM for the original 128K Macintosh (known as ROM 69), was 
universal with respect to system RAM size, and was also used in the Macintosh 512K. 


The Macintosh Plus and Macintosh 512Ke 128K ROM (known as ROM 75), had several universal 
features. It was available as a field upgrade ROM, along with an 800K floppy drive, for the 
Macintosh 512K, to transform it into the 512Ke. It supported the following features if they were 
present. 

* Memory size ranging from 512K to 4 megabytes. 

* If the 53C80 SCSI controller chip was present, the SCSI manager would support it. 


* It supported two different versions of the Real Time Clock / Parameter RAM chip. The original 
: one had 20 bytes of parameter ram, while the newer one had 256 bytes. 


* The Serial Driver suppqrted 


The Mac Plus serial pomts supported-Data TerminalE hilo the 512Ke did not have 
this signal available. 


¢ The Sony Driver suppor 


Nisk drivgs, the originaYsingle/sided 400K drive, the newer 
double sided 400K/800 


drive, and th¢ slow ndn-SCSI Harf Disk ZO. 


76), is ngt very yniversal. Unlike the Mac Plus 
ersalfehtures are as follows. 


* Memory size ranging from 1 to 4 megabytes. 


* It contained limited support for the Motorola 68010 and 68020 microprocessors, even though 
Apple never produced a machine using this ROM with those processors. 


* The Sony Driver supported 3 type of disk drives, the original single sided 400K drive, the newer 
double sided 400K/800K drive, and the slow non-SCSI Hard Disk 20. 


* A later revision of this ROM has been produced which contains a new Sony Driver that will 
support the SWIM chip and the FDHD disk drive if they are present. 
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The Macintosh II 256K ROM (known as ROM 78), was the first ROM for the open architecture 

Macintosh, it required a 68020 processor, and contained many new features, and was not compatible 

with any earlier machine. The universal features are as follows. 

¢ Memory size ranging from 1 to 8 megabytes. 

¢ Supported either the HMMU memory mapping unit, or the Motorola 68851 PMMU paged memory 
management unit. 


The Macintosh IIx ROM (also known as ROM 78, rev 1.3), is a fairly universal modification of the 
original Macintosh II ROM. It can be used in the original Macintosh II, the Macintosh IIx, the 
Macintosh SE-30, Cobra I, and is supplied with the SuperDrive upgrade for the Macintosh II. The 
universal features are as follows. 

¢ Memory size ranging from 1 to 128 megabytes. 

¢ Supported either the 68020 or the 68030 microprocessor. 


¢ Supported the HMMU, the 68851, or the built in 68030 memory management unit. 
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The Jaws 32 ROM 


Since there is only one 68000 based CPU in development (Esprit), and it is very far along, it would 
unfortunately be to disruptive to make it a Jaws ROM. Instead we will initially focus on the 32 bit 
Macintosh family. The Jaws 32 ROM assumes that it is running on at least a 68020 processor, and 
can be optimized to use the additional instructions and addressing modes that are not available on the 
68000. | 


Below are a list of the kinds of features that the ideal Jaws 32 ROM will support, and the envisioned 
list of possible implementations to choose from. 


If schedules permit, it would be desirable to include support for all prior machines that were supported 
by the Mac IIx ROM in the Cobra II ROM. This ROM could be used for a field upgrade to 32 bit clean 
memory manager support for the earlier machines. In the Cobra II time frame, it is unlikely that all of 
the 4 Square, or F19 features could be fully supported in that ROM. 

* Memory size ranging from 1 to 128 megabytes. 

* Supported either the 68020 or the 68030, and possibly 68040 microprocessor. 


¢ Clock Rates of 16, 20, 


¢ Supported the HMMU, pemory managemeny unit. 
¢ Supported either the 68 
¢ Support 680x0 IWM/SV 
¢ Support 680x0 SCC, or 


¢ Support either the Mac I 
interrupts. 


for NuBus and other external 
¢ Support RBV based onboard video, or Mac SE-30 onboard video, or no onboard video. 

¢ Take advantage of the SCSI DMA chip if present. 

¢ If and external cache exists, use it. 4 Square and F19 caches. 


* Possibly support the Big Ben clock/parameter ram chip. (if any CPU is going to use it). — 


¢ Support for detecting the Mac II, Mac IIx, Mac SE-30, and Cobra I/II, 4 Square, F19, and Spin 
logic boards, and the Columbo package. 
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The Jaws 16 ROM 


Since there is only one 68000 based CPU in development (Esprit), and it is very far along, it would 
unfortunately be to disruptive to make it a Jaws ROM. But we could begin development of a 
universal 16 bit ROM that would support all of the 68000 based 16 bit machines. This would be more 
important if a new low cost Macintosh, or a ROM upgrade for existing machines is being considered. 


Where things are 
This project is currently in the early stages, and is mostly unstaffed. More investigation is needed, and 


more progress is to be expected in the future when the demands of other projects subside, and more 
time can be spent on this project. 
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FourSquare/F19 
ROM ERS 


Version0.2 
January 13, 1988 
Bob Herold x5118 HEROLD1 27AJ 


Revision History 
August 28,1987 0.1 First Release of Modern Victorian ERS. 


January 13,1989 0.2 Rewritten for FourSquare and F19. 
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Overview 


The FourSquare and F19 machines are high end Macintoshes with near workstation perfor- 
mance. They include fast processors, cached memory architectures, DMA for the SCSI inter- 
face, and intelligent I/O processors for the SCC interface and the Sony & ADB interfaces. 
This document describes the ROM software being developed to support these new hardware 
platforms. 


Most of the software is common for both machines. Software specific to either one is identi- 
fied as such. 


- The ROM for these machines will be a ‘universal? ROM. The ROM will support 
FourSquare, F19 and all existing 68020/68030 Macintoshes as well. The software will de- 
termine the exact features of the machine and select the appropriate hardware dependent rou- 
tines either at run time or at start time. 
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Hardware Description 


SCSI DMA 


The SCSI DMA chip is an Apple-designed ASIC (Application Specific Integrated 
Circuit) that provides a DMA interface to the SCSI controller. It also provides all the 
features of, and supports the software written for, the 53C80 chip used in existing 
Macintoshes. 


The DMA interface consists of a 32 bit address register, a 32 bit count register, a pro- 
grammable watchdog timer, and control registers. It supports transfers to/from mis- 
aligned address, and non-modulo 4 counts. 


The 53C80 cell used in the chip provides up to 3 megabyte per second transfer rate, and 
automatic SCSI bus arbitration. 


IOP’s 
The IOP (Inqut/QutpatPrecesse z 6502-based intelli- 
gent I/O confroll¢r. Op 7s, one for the 8530 SCC 
(Serial Co et érs Woz Integrated Machine) © 
floppy contr@ller. ‘The A the peripheral chip. 
Major features of the chip are two DMA fi Ye 6502’s local RAM, a 16 bit 
programmapfe timer, and two digita} phase loc bd loopé (for high speed synchronous 
protocols sch as Fa ; KAM is Available to the 6502. 


space. The host has read/write access to the IOP’s RAM through a 16 bit auto-increment- 
ing address register and an 8 bit data port. The host can interrupt the IOP using a memo- 
ry mapped control register, and the IOP can interrupt the host 68030 using an interrupt 
line. 


For compatibility with existing applications/drivers that use the SCC, the IOP can operate 
in ‘bypass’ mode where the host has direct access to the SCC. All the SCC registers are 
then visible to the host processor. 


The IOP also has two digital I/O ports. These are used to modulate the ADB bus, elimi- 
nating the need for a separate ADB transceiver. 

FourSquare Unique Features 
Processor 


FourSquare uses a 25 Mhz 68030 and 68882. The 68030 synchronous bus is support- 
ed, with 5-2-2-2 clock burst accesses to RAM. 
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MDU 


The Memory Decode Unit is an Apple-designed ASIC that controls the DRAM in the 
system and generates selects for the I/O ships. The physical address map for the 
RAM is not contiguous - it consists of two banks of 128 megabytes each. The soft- 
ware is responsible for determining what size memory is installed in each bank and 
setting up a contiguous logical address space. 


External cache 
The external cache is a 64k instruction-only cache organized as 16k by 32 bits. A 
cache hit results in a two cycle read by the 68030. Burst reads of cache hits are not 
supported, as they are inefficient for a fast cache. 
A cache miss causes a retry from main memory. Burst and non-burst reads from 
main memory are supported during retry, including both wrap and non-wrap bursts. 
All writes (long word, word and byte) are cached to maintain coherency. 


The cache is controlled by two VIA bits. One enables the cache, the other is for 


flushing the cache. 
VIAs 
FourSquare has two WiAs-similar to the Madinifsh II. The WA’sAre configured as 
follows: 
VIA 1 
PAO facpOry 
PA1 cpu.id 0 
PA2 cpuNd 1 rtc gelect* 
PA3 
PA4 cpu.id 2 PB4 
PAS PB5 
PA6 cpu.id 3 PB6 External cache flush* 
PA7 PB7 
CA1 60.15 hz input CBl 
CA2 1 second* input CB2 
timer 1 (Sound Manager) timer 2 (Time Manager) 


FourSquare’s Cpu ID is $E (cpu.id 3 = 1, cpu.id 2 = 1, cpu.id 1 = 0, cpu.id 0 = 1) 


VIA 2 

PAO slot 1 irq* PBO External cache enable* 
PAI] slot 2 irq* PBI NuBus buslock* 

PA2 slot 3 irq* PB2 Poweroff* 

PA3 slot 4 irq* PB3 

PA4 slot 5 irq* PB4 NuBus TM1a* 

PAS | PB5 NuBus TMOa* 

PA6 PB6 Snd.ext* 

PAT PB7 60.15 hz out 
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CA1 NuBus slots irq* CB1 Sound irq* 


CA2 — SCSI irq* CB2 JOP SWIM irq* 
timer 1 timer 2 generates 60.15hz on PB7 
F19 Unique Features | 
Processor 


F19 uses a 33 Mhz 68030 and 68882. The 68030 synchronous bus is supported, with 
?-?-2?-? (to be determined) clock burst accesses to RAM. 


Memory Controller & Cache 


The F19 memory controller is an Apple-designed ASIC for controlling two banks of 
DRAM and a high speed cache. A 32k instruction and data cache is used. The memo- 
ry controller is programmable for several different processor speeds, RAM access 
speeds aus ROM a access speeds. It also provides accelerated page mode writes using 


fr event time-stamping, I/O 
§, and bus time-out logic. It re- 
e glue chip found in Macintosh 


F19 uses one VIA, configured as follows: 


VIA 1 

PAO factory* PBO rtc data in/out 
PAI cpu.id 0 PB1 rtc clock out 
PA2 cpu.id 1 PB2 rtc select* 
PA3 PB3 

PA4 cpu.id 2 PB4 

PAS PBS 

PA6 cpu.id 3 PB6 

PAT PB7 

CAI CB1 


CA2 1 second* input CB2 
timer 1 (Sound Manager) timer2 (Time Manager) 


F19’s Cpu ID is $D (cpu.id 3 = 1, cpu.id 2 = 1, cpu.id 1 = 0, cpu.id 0 = 1) 
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BIU’s 
F19 uses a two chip NuBus interface, BIU30 and BIU2, which replace the NuChip 


and associated buffers found on Mac II class machines. These Apple-designed chips 
provide a lower cost NuBus interface. The chips also support slave block transfer. 
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Software Overview 
Cobra II/MaclIIx base 


The FourSquare/F19 ROM will be a ‘universal’ ROM that can run on any of the 
68020/68030 machines. As such, it will include all the Spin, Cobra II and Macintosh IIx 
features. Many of these features have their own ERS. The features applicable to the 
FourSquare and F19 ROM are: 


revised slot manager 

32 bit Quickdraw 

async SCSI manager 

32 bit clean memory manager 

32 bit cleanliness in the rest of the ROM 

revised memory sizing for the new architectures 

Start Manager changes to support the new architecture 
remote booting support 


Universal ROM features 


The Universal ROM project is an effort fo alow a single KOMAmage to run on many dif- 
ferent hardwdre cpaffgurationss When the machine is fst bgoted the ROM code will de- 
termine which hardware axe available on thefnachyfie it is running on, and con- 


chines using | aking sysiém softwaré much fore maintainable, 2) porting to 
new hardwake archi és wouldAe reduced, o the simpler effort of supporting just the 
new hardware pgrades co e for the entire installed base if 
need be, 4) the fact save from buying a single set of ROM in huge quantities 


A new patching scheme that uses offsets within modules instead of hard coded ROM ad- 
dresses is also under consideration. This would allow us to make new versions of the 
ROM for future machines without obsoleting patches for code that has not changed. 
See the ‘Jaws’ ERS for more detail. 

Hardware support 
Many small changes are necessary in lots of places in the ROM to support either the 
FourSquare or F19 hardware. These include interrupt handler additions to handle the 
new IOP chips and the OSS’s soft interrupt priorities and interrupt status register, 
ShutDown Manager changes to support F19’s method of powering off, Start Manager 
changes to set up the new hardware to a default-state, and changes to equate files to sup- 
port the new hardware architectures, etc. 
See the ‘FourSquare/F19 Hardware Support’ ERS for more detail. 

Async SCSI Manager 


The Async SCSI Manager will already have shipped in the Harpo and Cobra II ROMs 
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before this machine. Modifications will be made to use the DMA channel available on 
FourSquare and F19. Using DMA is ideally suited to the asynchronous design of the new 
SCSI manager, in that no processor intervention is required during the actual data trans- 
fer. 


Since DMA occurs in physical address space, the Async SCSI Manager will also be mod- 
ified to determine the physical address of the data transfer buffers. In FourSquare with its 
physically discontiguous memory banks set up by the MDU, the SCSI Manager will 
break up transfers spanning the physical banks. 


See the ‘Async SCSI Manager’ ERS for more detail. 
IOP Manager 


The IOP Manager is a new system software service for setting up and communicating 
with the two IOP chips present in FourSquare and F19. It provides the ability to down- 
load 6502 code into the IOPs and start them running, and a message based communica- 
tion mechanism using the host accessible 6502 local RAM. All drivers written to use an 
IOP will use the IOP manager to communicate with the IOP. 


See the ‘IOP Managér’ ERS for more detpil. 


Sony Driver 


mented in the IOP, wi HeIT tx erface O the 68030 side seine 
Sony driver interface: 


See the ‘IOP Sony Driver’ ERS for more detail. 
ADB Driver 


The ADB driver will be modified to use the IOP SWIM implementation of the ADB 
transceiver. The IOP code will modulate the ADB bus manually using two ports on the 
IOP. This modulation will be interleaved with floppy activity. 


See the ‘IOP ADB Driver’ ERS for more detail. 
Appletalk 


A new Appletalk LAP layer for Localtalk, written in 6502 assembly, runs on the IOP 
SCC. Since the SCC has two channels, two LAP drivers can co-exist on the IOP, or one 
LAP driver and one serial driver. Other drivers can be written if they are deemed impor- 
tant - a possibility would be a MIDI driver. 


The LAP uses the IOP’s DMA channels to receive and transmit Appletalk packets. Ifa 


serial driver is also installed, up to 56 kBaud can be simultaneously support with 
Appletalk running. 
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The two driver architecture allows the IOP to be used as a bridge which runs in the back- 
ground with almost no processor intervention. 


See the ‘Serial IOP’ ERS for more detail. 
Serial Driver 


The Serial Driver is substantially modified to use the IOP SCC. The interface to clients 
of the serial driver is unchanged from existing implementations. 


See the ‘Serial IOP’ ERS for more detail. 
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FourSquare/F19 
Hardware Support ERS 
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January 13, 1988 
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Overview 


The FourSquare and F19 machines are high end Macintoshes with near workstation perfor- 
mance. They include fast processors, cached memory architectures, DMA for the SCSI inter- 
face, and intelligent I/O processors for the SCC interface and the Sony & ADB interfaces. 
This document describes the miscellaneous small changes throughout the ROM that are nec- 
essary to support the new hardware architectures. Major new software efforts for the IOP 
chips and the SCSI DMA chip are describes in separate ERS’s. 


StartTest 


StartTest (start up diagnostics) will have a new memory sizing scheme to support both 
FourSquare’s MDU and F19’s memory controller. It will also test a small area of RAM and 
use that RAM to return memory size information to the Start Manager. The information will 
be formatted as a table of pairs of 32 bit physical start address and 32 bit size for each chunk 
of memory found. 


StartTest will also dowrfload 1g the SCC to 
throw the IOP into bypa imi art Manager will 
be correct. 
On F19, StartTest will a : : S configuration registers 
for optimum performan¢e givgerttte 

Start Manager 


Changes to the Start 


1) Set up PMMU table i iceke S space from the various 
discontiguous chunks of ohiysical memory found By StartTest. 


2) For F19, set up interrupt priority levels in the OSS control registers. The interrupt 


levels will be: 
Level Source Sub-source Where Seen Used For 
level 7 debug 68030 debugging 
level 6 poweroff 68030 power up/down 
level 5 IOPSCC OSS int 7 IOP SCC 
level 4 slots OSS int 0-5 interrupts from NuBus cards 
level 3 sound OSS int 8 sound 
level 2. SCSI OSS int 9 reselection, data transfer 
level 1 IOP SWIM OSS int 6 IOP SWIM 
VIA1 CA2 OSS int 11 1 second interrupt 
CA1 OSS int 11 (not used) 
SR OSS int 11 (not used) 
CB2 OSS int 11 (not used) 
CBl OSS int 11 (not used) 
T2 OSS int 11 timer 2 (Timer Mgr) 
Tl OSS int 11 timer 1 (Sound) 
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60 Hz OSS int 10 fake vertical blank 
3) For F19, change the interrupt vector initialization to match the interrupt priorities. 
4) For F19, disable/re-enable slot interrupts using the OSS. 
5) Add an initialization call for the IOP Manager. 
6) Do not initialize the SWIM, as the IOP Sony driver will do this later. 


7) Set up the VIA(s) according to the new architecture. 


Interrupt Handlers 


The interrupt handlers must change to work with the new sources of interrupts, namely the 
IOP chips. The SCSI DMA chip interrupt come in the same way as on the Mac I, so only 
the SCSI Manager need worry about how to support it. 


On F19, all ETUDES © come e throug} he OSS chip. lf ‘Multiple interrupts are configured at the 
same level, the inte “must change Be arrupt status register to 
efi. Alsq, the 60. 15 hz interrupt andler must reset the 


On F19, the shut Powgr-Off control register to turn | 


off the machine. 


owy/managex must ust the OSS chip 
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Remote Booting Preliminary ERS 
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1. Overview 


The purpose of this document is to present the issues involved in 
implementing remote booting as a feature of the next ROM released 
which will be used in Spin, Cobra II, and Four Square. It will be used to 
help determine the resources and time required to implement remote 
network booting. Issues that need to be addressed prior to design and 
implementation are discussed in later sections. Although, this 
document does not contain a design proposal for remote booting, it does 
offer suggestions on ways of implementing certain aspects of remote 
booting. 


Since the Apple II group is currently re-designing their implementation 
of remote booting, we may be able to coordinate our efforts with 
theirs. Conceivably, the Mac Il and Apple Il could use the same 
protocol. This will be evaluated when the protocol is designed. 


The major areas reewiri 
1. ROM 


4. Server Appletz 
5. Utilities 


Detailed information regarding the changes required to each section 
will be given later. In general, the ROM must read the boot information 
in a multi-stage process from a server. Each stage will provide the 
information needed to go to the next stage. The system file and system 
folder information stored on the server will be split into two general 
pieces. 


1. Resources/files necessary to boot. 
2. Resources/files which are optional. 


Among the optional resources are fonts (which are read-only even if 


they are optional) and AppleShare prep files (which are read/write). 
Most of the required resources are read-only. 
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Remote booting will require a multi-stage log in. The stages for 
booting are: 


1. ROM reads boot blocks 0 and 1 from the boot server. 
2. Blocks 0 and 1 are executed. They include reading of the 
Appleshare external file system from the boot server. 

3. The external file system (altered) then executed. It contains 
enough information to log onto an AppleShare file server in a 
potentially temporary way and access a generic system. The 
generic system will allow booting of the workstation to the 
point that a regular log on dialog can appear. 

4. The user logs in and his/her specific system is loaded. 


For the Apple Il, the first thing that happens is that the system looks 
for the server name. An ATP request is made and blocks 0 and 1 are 
loaded one block at a time. Boot blocks 0 ane 1 are executes which then 


in our case, ® 
external file 
We can usé 


Apple Computer Confidential Thursday, September 29, 1988 3 


2. ROM Issues 


The intent is to add a minimum number of hooks in the ROM to support 
remote booting. Once minimum ROM support is available in the ROMs, 
the rest of the code can be implemented at a later date. The initial 
design must be thorough so that enhancements can be made to the 
initial remote booting feature set. 


Currently, a CPU will boot up from a floppy if it is present. If a floppy 
isn't present, it will boot from whatever device is indicated by PRAM. 

lf PRAM is not initialized and a floppy is not present, the CPU will 
attempt to boot off an HD20 or a SCSI device depending on which device 
it finds first. How to handle network booting when PRAM is 

uninitialized is unclear (refer to issue 4). 


Information in PRAM about the boot up device is stored in a word which 
indicates if the boot up device is gA-+iD20, a SCSI device, or a slot 


device and write PRAM accordingly. 


If the network is selected as the startup device, the ROM needs to call 
code which "reads" boot blocks 0 and 1 via the network from a “boot 
server". The boot protocol needs to be defined. Blocks 0 and 1 would be 
executed and perhaps using the same protocol but a different image, 

_ read in the Appleshare workstation external file system code. This 
enables the workstation to access the AppleShare file server to get the 
rest of the sytem information needed to mount the boot volume and 
provide login access. The boot process would then proceed as normal. 
If PRAM is set to identify the network as the boot device, the startup 
code must be modified. The current implementation looks for a drive 
queue entry. For a network configuration, the code must either 


1. not look for a drive queue or 
2. it must implement a phony drive queue with a driver 
that reads blocks 0 and 1. 
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3. System File and Folder 


The system file will be seperated into two parts : 
1. Resources that are necessary 
2. Resources that are optional 


Some of the resources are read/write, therefore, a copy of the resource 
‘must be given to the user. Those that are read-only need to have 
"pointers" to the actual system file resource. To determine which 

parts would be required for all users, each file/resource in the system 
was evaluated (refer to Appendix A). 


It is desireable that the common optional read-only resources such as 
fonts be stored in one place on the server and that each user be able to 
select which ones he wants in his system file. These are the “user 
selectable” resources. The,user must also be able to have private 


1. 


2 
3 
4. 
5. 
6 
7 
8. Startup application 

Each of the resources evaluated in Appendix A is loaded in at different 
stages of the startup process. This information was used to determine 
which resources were needed and when. 

The system folder can also be split into required and optional parts. 


Resources in either section of the system folder can be read/write or 
read-only. 
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3.1. System File Diagram 


User System File Server System File 


(Patches, 
Misc. 
Resources, 
INITs<31) 


Font File 


a 


User Selectable Resources 
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3.2. System Folder Diagram 


THIS PAGE INTENTIONALLY BLANK 
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4. Workstation Appletalk Booting 


A major issue for workstation Appletalk booting is whether we should 

make the protocol for the MAC II family the same as the protocol for 

the Apple Il. For the Apple ||, 200K of code is brought in at boot time. 

The MAC II would require about 70K of code to be loaded in at boot time 

for patches alone. We need to evaluate how much code is essential at 
boot time and how much of the code can be brought in later especially 

for large files such as the Finder. The Apple II group is looking at using 

a broadcast booting protocol. This protocol is not feasible for the Mac 

ll since AFP is used to read the System File, Finder, etc.. 


There are two methods to get the booting information from the server. 
Broadcast : The server sends out all the information via the 
network and workstations listening in can pick up the 
blocks they need. 
Serial : Send each workstation the blocks of boot information 


network is conneé owever, Appletalk 2.0 will allow any 
number of devices to be hooked to a network. The zone the node is 
in must be specified, but the server must still be in the 

workstation zone. The boot zone will need to be specified in 

PRAM. 


SERVER : As there are potentially many servers that can be on a 
network, the name has to be saved in PRAM. 


USER NAME : The user can type this in given that we have some 
system functions available (text edit and dialogs) or store this 
in PRAM. 


PASSWORD : Same as user name. 
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Another way to do this would be to store the server name and an 
integer in PRAM. This integer would be a unique ID generated by the 
AppleShare file server when 2 user set up his/her boot image on the 
server. That number would be sent to the server and converted to his 
name and that persons boot image would be sent back to the 
workstation. This second scenario would obviously involve much more 
work in the AppleShare server side. 


lf everything is stored in PRAM, memory allocation is as follows: 
32 bytes server name 
33 bytes zone name (for AppleTalk 2.0) 
32 bytes user name (optional) 
8 bytes user password (optional) 


The same scheme as above except use 2 bytes for the user 
name which requires translation by the server software. 


An important requirement uel he remote booting system ig that it 


will not be read = release of this d since it is 
only used fo OcaTalk devices, cards wit hav¢ to implement 
parts of it. Cards already do some of this wgrk sinCe they must do 
AppleTalk 2 lation alfeady becAuse tile code is not in ROM. 
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5. Server Appletalk Booting 


The AppleShare server side may require extensive changes for remote 
booting. The amount of work required will vary greatly depending on 
whether an ID is stored in PRAM and the server has to convert it or if 
the entire name and password are stored in PRAM. The first scheme 
requires 10 bytes (2=user ID, 8=pwd). The second scheme requires 40 
bytes (32=user name, 8=pwd). 


Another issue that needs to be addressed is how to administer files to 
allow copying the system in one place. Lastly, we need to look at the 
setup utilities and determine whether we can use utilities similar to 
the ones used by the Apple II group. 
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6. Utilities 


Some of the utilities that will have to be provided for a remote 
booting system are : 


* Requesting the version number of the system 
* Provide a utility for a user to set up his remote booting image. 
Includes | 

-selection of resources and files on his/her system folder 
on the server (fonts, DAs, Cdevs, etc.). This can be done 
the way Drawll implements font selection which adjusts 
the font menu. 
-what version (6.0.2, 6.0.x, ..., finder version) 
-where on the server it is to be kept 

* Server side 
setup system file and folder and update on the server so 
that all boot fqiders are updated. 


A major isste for remote boofing is fow files will be admipistered. 
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7. Issues 


For test purposes, a bit from the attributes bits in the Resource 
Manager can be used to indicate whether we want to use resouces local 
to our system or whether resources should be pulled from the server. 


However, many unresolved issues still exist. A few of these are listed 
below. 
General issues: 
1. Why is there a laser prep file? Does it just contain a name? 
Can other printer drivers be changed to use a prep file? 
2. Will this scheme of splitting the system file work with 
NuFinder? 
3. Why is there not default dctb 0? 
4. When a machine is first turned on (i.e. PRAM has not been set 
yet) and there is no floppy and hard drive or SCSI device, 
should we automatically-bept off the network? 


Nata packets. 
a packets? 


Apple Computer Confidential Thursday, September 29, 1988 12 


8. Appendix A 


To implement remote booting, the System File and System Folder 
must be split into two parts, a required part and an optional part 
for each user. Each section will have read-only and read/write 

_ portions. This appendix shows the slit of the System File and 
Folder . 


SYSTEM FILE SPLIT 

Read/Write Parts 
cctb 
dctb 
STR(user name 
STR(spool fidr) 
STR(printer type) 
wctb 

oe pad selectable) Parts 


Apolestiare prep 

Closeview 

User added (Inits, CDEVS, RDEVs) 
Read-only Parts 

CDEVs (i.e. Finder, General, Keyboard...) 

Printer Driver (7?) 

Appleshare (RDEV) 

Responder 

MacroMaker 
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NFS 4.0 and/or Network booting 


Holly Knight 
€ Apple Computer, Inc. 


ABSTRACT 


Diskless, “low-end” networked work stations sharing expensive high-end 
diskfull servers are a low cost solution to office and educational computing 
needs. Recent NFS under UNIXf developments make supporting diskless opera- 
tions for NFS based systems feasible. At Apple, network booting is being exam- 
ined and implemented for Macintoshes under the native Mac OS. The A/UX 
group should usé these two supporting efforts to create a diskless workstation 
that runs A/UX and may serve and be erver eee 
ture. I will discuss d i : 
work booting, the 


1. Motivation 
The A/UX kemel provides 


environment, serving and being~«% 
We need to upgrade A/UX 


In addition to being the cuk 
diskless operations. The new; i 

system, and allow the system to either serve oe or be a client from, any remote machine architec- 
ture. Serving or clienting comes in two parts, booting, and what I will call diskless operations. 


There are several implications of the latest NFS release. All machines running the Sun 4.0 NFS 
code will be able to act as servers. Diskless operations have been made available for any NFS 
supporting UNIX system. Interoperation will be increasingly expected. 

The Mac side of Apple is contemplating diskless booting, and Mac ROM support for this kind of 
operation is to be added to Cobra II, Spin and Four-square. I presume that the support for net- 
work booting will also be included in any subsequent ROM releases. 

With the upgrade of A/UX to the 4.0 NFS release, we will be able to support NETdisk (diskless) 
operations. Diskless operations allow us to sell diskless Macs, and operate diskless and floppyless 
Macs running A/UX. The latter is very desirable in the higher-ed market. 


2. System Requirements 


2.1. ROM Support 


The ROM support for network booting under the Mac OS is still in its design phase. An initial 
ERS on Mac OS network booting has been released, and some of the issues have been discussed. 


¢ UNIX is a trademark of AT&T Bell Laboratories. 


-2- 


Appended to this document is the Mac network booting ERS, and meeting minutes. The Mac 
approach to network booting is to use Appletalk over local- and ether-talk as the communication 
protocol stack. The files to be booted will be stored on an Appleshare server. 


Networking for A/UX is intended to allow the Apple machines to run in a multi-vendor ethernet 
environment. Apple proprietary protocols to not fit well with this intent, hence the A/UX group 
is primarily interested in the very early decisions made during the Mac OS boot sequence.* 
Network booting, with respect to A/UX requires an Apple ethemet board. ** 


We will need space in ROM to support at least RevARP or bootp, a minimal IP (Intemet protocol 
layer), UDP (User datagram layer), TFTP (Trivial file transfer protocol) and an ethernet driver. 
In addition, we will require the boot sequence to notice that there is an ethemet board, and try to 
load and boot the system using the A/UX boot code in ROM. 
The initial PRAM contents will specifiy that Mac OS is to be the default boot choice. If there is a_ 
disk or floppy those will be used to boot. If there is no disk, then network booting is the final 
option. : 
In the booting sequence, when the network booting is being tried, the first choice will be to try an 
appletalk boot, the second an A/UX boot.*** Unfortunately, if the user wanted an A/UX boot, 
and gets a Mac boot, he will e Mac OS boot, and then run a new (yet to be deter- 
i OT TeTU it—With PRAM now con- 


Initialization happens ‘ i ¥ system is tumed on. It is clear that 

x, Wi Is it possible that if an A/UX boot is 
the ONLY option fhat su fe boot option will be the default 
for subsequent boots (from pet’ PRAM be set during the boot sequence to 


The whole issue of what sequence is followed for booting needs work. In the educational 
environment, do you want to prevent disk booting if network booting is selected? What if you do 
want to switch back to disk booting? 


2.2.2. New Utilities 
Under the Mac OS and A/UX, there needs to be a utility to manage PRAM. The selections that I 
can think of are: 
e  Toselect A/UX-or Mac OS for default network booting. 
e _ To install hostname, domain? name, intemet address, kernel name, machine architec- 
ture, autoconfig options 
e Tochange hostname, domainname, and internet address, kernel name, machine archi- 
tecture, autoconfig options 


* Using appletalk protocols would preclude our being able to boot and run off of non-Apple servers. 

** I am not sure this is an acceptible solution. Do we want to use drivers located in ROM on vendor supplied. 
boards? This has the problem that drivers on boards may not be compatible with current releases of the OS. 
** We do not yet have any agreement to “time out” the sppletalk boot, or even support the notion of an 
A/UX boot in ROM. 


2.3. Boot sequence 
The anticipated boot sequence is: 
e _ Use reverse ARP (or bootp) to determine the internet address that corresponds to our 
ethemet address. The responding host will probably be the NFS root server for the 


requesting Client. 

e Use TFTP to get the boot program, in our case the whole OS? or some intermediate 
standalone program?® 

e Use bootparams or bootp to discover server name and remote mount points for root 
and swap.** . 


e NFS mount and access for normal OS operations. 

e Reconfigure the kemel? 

© Move to multi-user mode, mounting the “standard” file systems via NFS. 
Note that after PRAM has been initialized with host name and address, we do not need to do 
RevARP step above.*** | 


At this point it is not clear if we want to try to boot sash and then have it boot A/UX, not a popu- 
lar view with the educational market,**** or jyst-boot A/UX directly. If we boot A/UOX directly, 


param can not be stored, Ue he SUTV ae specify’ wheyé root, swap and 
dump live. The address of the : 


3.1. ROM software 
At this point there is NO / 
Ethernet driver 


RevARP 

New PRAM initialization code? 

Bootparam or bootp 

NFS mount ; 

e _Initialization code for auto_data (see "What sash does for A/UX") 


I am not sure what will be needed for the initialization code for auto_data. What is booted, a ker- 
nel, or some intermediate program, will determine whether or not the new NFS mount code is 


® The address of the server is available in the response to the RevARP or bootp request in step one. If the 
server does not respond, the TFTP request will be broadcast. 
** Bootparams and bootp are Sun Microsystems and Stanford University resepective answers to the network 
booting question on how to respond to diskless clients queries for addresses, boot files, etc. , 
#82 Note however that if the host is moved between nets, we will need to timeout the “known state” boot, and 
try to rediscover our intemet address. 

#9** Sash represents a giant security hole. 


required. 


3.2. Net Booting mechanisms 

Using either bootp, or RevARP we figure out who we are. I have not yet decided which of the 
two available approaches to getting our intemet address we should use, but, let us assume that we 
have now somehow figured out who we are, and are ready to load up a program, either a kemel or 
some intermediate step that I will call netsash. 


3.2.1. What sash does for A/UX 
In the current system sash is booted by the Mac OS ROM, and runs before A/UX. Sash builds up 
a structure in low memory which contains the information about the cards in the system. The ID 
and version number from each card are stored. Sash also saves the SCSI ID, sub ID and eschatol- 
ogy cluster of the root. In particular, sash initializes the structure auto_data defined in 
sys/module.h. Sash then loads and boots A/UX. 

In either of the following cases, “Booting A/UX" or “Booting netsash”, either these sash jobs 
must be done by the booting program, or the kemel must not expect them to be done. 


3.2.2. Booting / 


Using TFTP we load 

I can see several ways th ang rune svaitable-AgkJX gould work. I can not 
even guess what the a ing i whicW one or combination of 
several is the "right"jsol 


bility. The idea is that you WOuld boot some minimal kemel, and then load in desired modules 
either from some sort of configuration file, or on user demand. On the fly autoconfiguration is 
fairly frightening for me to contemplate; it may not even be possible. The flexiblility of loading 
the modules you want, and having them immediately available without a reboot sounds pretty 
good to me. 

The second option and third options start by loading a huge kernel with “everything” in it. This 
notion may be unworkable due to object conflicts. 

The second option would allow you to remove sections of the kemel, and the third option would 
limit changes to the kernel to reconfiguration of kemel software to match hardware 
configurations, and perhaps kconfig options. One easy example of the kind of reconfiguration 
intended is, for instance, if the ethernet board on the client system is not in slot 9. The ethemet** 
driver would need to look at configuration tables to determine the number and Nubus slots that 
contain ethemet boards. This kind of reconfiguration would not require relinking of the kemel, 
but would require work by every Nubus driver to determine its location. 


Enforced standard configurations, is less flexible, most easily do-able, and will probably be what 
we end up with. The server maintainer would create several kernels supporting “interesting” 
software and would make them available to network hosts. The software in the kernel could 


*¢ Read all drivers that care about their slot location. 
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include both Apple and non-Apple modules, supporting both Apple and non-Apple hardware. 


e PROS 
Simple model. 
Small amount of new code. 
e- CONS | 


Inflexible, unless one of the complicated options above is provided. 
Most of the work to implement this must be done by the kernel, to the kemel. 
All drivers must conform to a new “standard” to allow on the fly reconfiguration. 


3.2.3. Booting Netsash 


Using TFTP we load netsash and start it. Netsash then mounts root, swap, dump and sundry 
other filesystems. With all these niftily available file systems netsash locates one of, a 
configuration file, a pre-built kemel, or a “standard” kernel. 


The standard kemel contains some default set of modules; NFS, BNET, an ethemet driver, tool- 
box, and the tape driver, for example. A new mini-autoconfig (available on the newly mounted 
file systems!) is envoked to reconfigure device tabtes for the client configuration, and the system 


is started with the in-core copy of A/U2 
If netsash discovers a conf sing ‘ally: from the 
modules found in some standprd Ibcation, a kemel, with 2 exed options, includ- 
ing: 

e Kconfigurable pa 

e Software modules, 

e Other stuff, that Lea 
The kemel is also configure client hary . This newly. created ker- 
nel may possibly be stored : Wie system ag the defajult for this client. Some 
possible concerns about storing the ks tsash are 

@ Make the choice a user selectable option, by dialog box? as one paramater in the 


configuration file? 


e Store the kernel by default because it is very slow to create a kernel, and who wants to 
wait to build a kemel each time the system boots. 


Having a client specific kernel is dependent on having the root filesystem on the server be unique 
for each client* 


If we are to support client configurable kemels then this is one possible method by which the 
pre-built, client specific, kernel is created, and stored. Client configurable kemels could still be 
created and stored using what we know and love, i.e., /etc/newunix, autoconfig, and kconfig. 
Once any one of the above kemels is in core, netsash finishes with whatever other initialization is 
required, and launches A/UX. Note that the user is not asked any questions while netsash is run- 
ning.** . 

e PROS 


* I believe this is the case, but will need to research it further. 
** Do we want to have user interaction/dialog boxes available at this intermediate step? The configuration 
file could be created at this point rather than from a running A/UX box. This might remove one more boot. 
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No linking of the kernel while the kernel is running, a difficult/impossible job. 
Very flexible for client specific requests/kemels 


Most users would have a "standard" kemel available, no proliferation of kernels for 
slight hardware configuration differences. 


Potential for user interaction at boot time. 
e CONS 
Potential for user interaction at boot time, a security risk? 
Very slow boot possible. 
Fairly complicated. 
A fair number of changes and new code required. 


I am inclined to think this is the most interesting path to follow. The booting is broken into 
pieces, and not all of the work would necessarily have to be done at the same time. We could get 
the ROM code through TFTP working, then get netsash working non-interactively. We could 
then add netsash interactions, and kemel configurations done, etc 


3.3. Filesystem Changes 


Are we going to foll . ilesystem organization? This 
does not seem ‘worth wile to mE, K thi q that often clients than 
servers. Four-square 
Where will served rox 
We will need to fig padabl¢ by non-A/UX boxes. We 
will/should need to gOme file $ stem dirdctories to makg/what ig served the same, or at least 


The client kernel will have to be able to use the new special nodes as root, swap and dump nodes. 
4. Issues 


4.1. Apple specific vs General mechanism 


Do we want to serve and be served using the "internet standard” facilites. Do we want to use the 
Apple scheme to boot (for example) and then use standard NFS for filesystems and root and 
swap. Do we want act as an apple protocol boot server and then act as an NFS swap, root and file 
server? 


De we want to use the apple scheme to boot sash, and then have sash launch A/UX? 


4.2. sash, to be or not to be. 
If sash is to be eliminated as a step towards booting, do we want to continue supporting sash? 
Do we want to use a floppy to boot SASH and then a kemel, but have all other files served via 


NFS. This would mean a switch from the root on the floppy to the root over NFS, but only after 
the boot. 


Se 


4.3, Error non-recovery. | 
If a server goes down, how do we let a user know that that is what has happened to his system? 


4.4. How to support non-Apple ethernet cards. 


If the ethernet driver is in ROM, and the only board we know about is our own. Where does this 
leave ethernet board vendors such as Kinetics? 


4.5. Bootp vs Bootparamd 


Which of the two incompatible boot protocol schemes should be supported? Bootp is in the pub- 
lic domain, but does not answer the NFS pathname for root, swap and dump question. Boot- 
paramd both passes back internet addresses, and NFS information, but is more complicated, and 
example PROM code is not available. 
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IL. Changes between NFSSRC 3.2 and NFSSRC 4.0 


This section describes the major changes between the previous release of NFSSRC 
(3.2, 3.2.1, or 3.2/4.3) and this release (NFSSRC 4.0). The purpose of this section is to 
allow licensees with previous versions to easily tell what's new. Following sections 
will describe all the differences between BSD 4.3 and NFSSRC 4.0 for new licensees. 


NETdisk client and server support 


A major feature of this release is the NETdisk client support. NETdisk server support 
was released in D/NFS 1.0. This release includes all of D/NFS 1.0 NETdisk server 
code and the administrative utilities for installing a diskless client’s files on an NFS 
server (usr.etc/netdisk). In addition, it includes code to implement diskless clients. 
Some of the changes to support diskless clients, such as the specfs virtual file system, 
were included in the 3.2 releases. 


The code to implement a disklessclient that will boot and swap to an NFS server is very 
hardware deppt Ge intluded prt msevisthe-SunQOS code that allows 


figures very strongly in this mechanism, of course. PRO not included in this 
release. In ¢ Opesations tha d by the boot PROM are 
described. s.will hava to design their gAn bogt procedure to fit into the 
NETdisk mod is included Pere as/an example 

Sun has reofganize make supporting Aliskless clients more efficient. 
This release\uses 4.3 file organizati@n. For information on how to 
organize the 1 fOr diskless flients, [see the hier_sunOS(8) and 


filesystem_sunOS (7) man pages. 


In testing this release, the VAX was used as a NET disk server to a diskless Sun. 
Because booting is such a hardware—dependent process, the VAX was not tested as a 
diskless client. The code included in this release to implement diskless client booting is 
the SunOS code and may have to be changed to implement a particular licensee's 
diskless client. | 


Theory of Operation 


The general booting procedure is discussed in the boot man page 
(man/man8/netdisk_boot) which should be read in conjuction with this description. 
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Booting consists of several interacting procedures: 


— nd bootblock request (sun2 client only) 

— Reverse arp 

- tftp get of the boot program 

‘— bootparams query to discover important identity information 
— nfs mount and access for loading operating system 


The server daemons handling these requests in NETdisk servers are, respectively: 
ndbootd, kemel REVARP handler, in.tftpd, rpc.bootparamd, and rpc.mountd and nfsd. 
(Reverse arp is handled by a user-mode daemon in Sun NETdisk servers.) 


Here’s how these operations are used together. The client, when booting, knows only 
its ethernet address. This is used in a broadcast reverse arp request to discover its IP 
address. The NETdisk server will respond to this request if and only if the arp mapping 
has been loaded into the kernel arp table (as a permanent entry) with the arp command. 
Note that ndbootd takes care of this automagically for a sun2 client. 


The file to be downloaded via‘sftp-i (i boot program. Sq that there is no need 
for information passed bet ing-piiases, the boot program will also do a revarp 
request as above. Boot then sends a Scqknae whoami request (directed first to the 
responding server, then broadcast, as with tftp). The result of this RPC tells the client 
its hostname, domainname, and IP address of an acceptable IP router. A second 
bootparam procedure (getfile) is then used to determine the NFS directory where the 
operating system image can be found (i.e., the client’s root pathname). This pathname 
is used in an NFS mount request to get the directory filehandle, which is then used in 
normal NFS lookup/fead procedures to load the OS (default is vmunix). See the 
bootparam* man pages for more info. 


Once the kernel is loaded and running, it does revarp and bootparam requests. In 
addition to getting the pathname for the root, the kernel also gets pathnames for swap 
and dump. Default keys used in the getfile requests are root, swap, and dump, although 
these may be overridden if the boot flag “-a” is given to the Sun prom monitor boot 
command (i.e.,“>b ie()-a). If bootparamd discovers that there is no value for the dump 
key, it returns a null value. The client OS will then use the swap device for this 
function. 
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Administrative differences to note in NETdisk 


There is only one area where procedures have changed relative to existing NFS 
administration; other differences are additions. This section describes the change and 
lists the additions. See the netdisk_install (8) and exportfs(8) man pages, along with the 
sample files in samples, for full description the overall administrative situation. 


The change is in the way that filesystems are exported by the server. Previously, only 
the root of a local UFS partition could be exported. Clients were free to import (mount) 
any sub-tree of the exported filesystem, but the server had no way to control this. In 
addition, there was an unsupported (provisional) exportfs system call which allowed 
the filesystems to be exported read-only, and to allow an arbitrary uid to be provided 
for mapping incoming requests with a Client root uid. 


In order to fully support client root partition access and control, it is necessary to extend 
the exporting scheme. The new scheme allows the server to export any arbitrary ( but 
still UFS) pathname with the restriction that no exported path may be either a strict 
subset or superset-e r zed-pathname-within the same physical 
better way to provide export 


ge. In addition, a 


options to th provided. EW Export option upported are ro, rw, 
anon, root, 

The exporting befoke a client can AAount/them is mandatory. If a 
pathname has not been explicitly ex} orted by the gerver, ¢lients may not mount it (and 


alid filehandles issued by the 


New administrative procedures involve installation of clients and maintenance of the 
/etc/ethers and /etc/bootparams files (or YP maps), and the /etc/exports file. 


Obtaining Sun binary distribution tapes (SUNBIN) 


For details on obtaining copies of the current SunOS distribution tape for use in tesung 
your NETdisk server product, please contact the ONC/NFS Technology Marketing 
Manager at Sun (K.C. Chan). Details on providing this distribution will be handled on a 
case—by—case basis. 


Once your NETdisk Server product is released, your customers must obtain a binary 
distribution tape for the workstations they wish to support from your server. The 
customers should order this tape (in a format suitable for loading on the server) from the 
supplier of the workstations. Alternatively, your company may wish to supply these 
tapes to your customers as part of a package arrangement. Details of licensing SunOS 
in this manner will be handled on a case-by-case basis. Contact K.C. Chan for more 
information on this, also. 
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Secure NFS 


A server can now export sub-directories, not just whole physical partitions, and 
those directories can be exported with the secure option. If the client then 
mounts the directory with the secure option, Encrypted RPC will be used as the 
authentication mechanism. Secure NFS protects against a user masquerading 
as another user. If a client mounts a directory that has been exported with the 
secure option, but does not specify secure in the mount command, access will 
be allowed by the user as an anonymous user (nobody). This access can be 
denied on the export by setting the anon parameter to —1. A new system call, 
exportfs, is used to handle the new export options. 


For more information about Secure NFS, see the mount(8) and exportfs(8) man 
pages, and the Secure Networking chapter in the “ONC/NFS Protocol 
Specifications and Services Manual”. The source for the exportfs user program 
is in usr/src/usr.etc. 


_ Encrypted RPC 


keylogin(1), key 


Unfortunately, the U.S. government does not allow export of the source code 
for the DES algorithm, so the /usr/src/lib/libc/des library has been gutted on the 
export version of the tape. The structure for Encrypted RPC is there, but the 
actual encryption algorithm is not. 


Domestic licensees should be aware that they must get a special license to 
export the DES libraries, even in binary form. Please see the letter that came 
with your tape for more details. 


Automounter 


A new service has been included that automatically mounts NFS partitions. 
Net-wide naming of directories is now possible (e.g., /net/machine/usr/bin). 
See the automount(8) man page for details. 
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Miscellaneous 


o Groups: 
Groups handling by RPC and NFS has been fixed to accomodate all 16 groups 
in 4.3 BSD. This is not in compliance with the protocol specification, which 
handles only 10 groups. 


o in.® 


In the 4.2 reference implementations, the non-RPC services that were under the 
inetd were prefixed with “in”. This is not the case in the 4.3 version. 


o inetd: 
Inetd no longer consults the /etc/servers file for configuration information but 
instead uses the inetd.conf file (as in BSD 4.3). 
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NAME 

bootparams — boot parameter data base 
SYNOPSIS 

/etc/bootparams 
DESCRIPTION 


The bootparams file contains the list of client entries that diskless clients use for booting. For each disk- 
less client the entry should contain the following information: 


name of client 
a list of keys, names of servers, and pathnames. 


The first item of each entry is the name of the diskless client. The subsequent item is a list of keys, names 
of servers, and pathnames., 
Items are separated by TAB characters. 


EXAMPLE 
Here is an example of the /etc/bootparams file: 
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NAME 
sunboot - start the Sun system kernel, or a standalone program 

SYNOPSIS 
>b [ device [ (¢, 4p) }] [ flename } [-a } boot-fiags 
>b? . 
>b! 

DESCRIPTION | 
The boot program is started by the PROM monitor and loads the kernel, or another executable program, into 
memory. 

The form b? displays all boot devices and their device arguments. 
The form b! boots, but does not perform a RESET. 


USAGE 
Booting Standalone 


When booting standalone, the boot program (/boot) is brought in by the PROM from the file system. This 
program contains drivers for all devices. 


| client then sends a TFTP 
asts the request). The filename 
representation of the client’s 


vmunix (or a standalone program). In order to do this, the boot program makes a broadcast RARP request 
to find the clieat’s IP address, and then makes a second broadcast request to a bootparamd(8) bootparams 
daemon, for information necessary to boot the client. The bootparams daemon obtains this information 
either from a local /etc/bootparams database file, or from a Yellow Pages (YP) map. The boot program 
sends two requests to the bootparams daemon, the first, whoami, to obtain its hosmame, and the second, 
getfile, to obtain the name of the client’s server and the pathname of the client's root partition. 

The boot program then performs a mount(8) operation to mount the client’s root partition, after which it 
can read in and execute any program within that partition by pathname (including a symbolic link to 
another file within that same partition). Typically, it reads in the file /vmunix. If the program is not read in 
successfully, boot responds with a short diagnostic message. 

Booting a Sun-2 or Sun-4 System Over the Network 

Sun-2 and Sun-4 systems boot over the network in a similar fashion. However, the filename requested 
from a server must have a suffix that reflects the system architecture of the machine being booted. For 
these systems, the requested filename has the form: 


ip-address.arch 


where ip-address is the machine’s Internet Protocol (IP) address in hex, and arch is a suffix representing its 
architecture. (Only Sun-3 systems may omit the arch suffix.) These filenames are restricted to 14 charac- 
ters for compatibility with System V and other operating systems, Therefore, the architecture suffix is lim- 
ited to 5 characters; it must be in upper case. At present, the following suffixes are recognized: SUN2 for 
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Sun-2 system, SUN3 for Sun-3 system, SUN4 for Sun-4 system, and PCNFS for PC-NFS. 


Note: a Sun-2 system boots from its server using one extra step. It broadcasts an ND request which is inter- 
cepted by the user-level ndbootd(8) server. This server sends back a standalone program that carries out 
the same TFTP request sequence as is done for all the other systems. 


System Startup 

Once the system is loaded and running, the kernel performs some internal housekeeping, configures its 
device drivers, and allocates its internal tables and buffers. The kernel then starts process number | to run 
init(8), which performs file system housekeeping, starts system daemons, initializes the system console, 
and begins multiuser operation. Some of these activities are omitted when init is invoked with certain 
boot-flags. These are typically entered as arguments to the boot command, and passed along by the kernel 


to init. 
* OPTIONS 

device One of: 
ie Intel Ethernet 
ec 3Com Ethemet 
le Lance Ethernet (Sun 3-50 system) 
sd + 
st SCSI 1/4" tape 
mt Tape Master 9-tre 
= : 
xy | XKylogicst 

c Contro errO.j i indigated type of device. 

we. Unit n 

filename Name fartition/ such as stand/diag or vmunix. 
Note: (filena ted de and partition. It never begins 
with ‘ gram uses a default value (nor- 
mally the boot executable file supplied 
by Sun, but Curbe-pa d mrdaione program loaded using adb(1). 

~a Prompt interactively for the device and name of the file to boot. For more information on 
how to boot from a specific device, refer to 

boot-flags The boot program passes all boot-flags to the kernel or standalone program. They are typi- 
cally arguments to that program or, as with those listed below, arguments to progams that it 

- invokes. 
—b Pass the —b flag through the kernel to init(8) to skip execution of the /etc/re.local 
—h Halt after loading the system. 
8 Pass the —s flag through the kernel to init(8) for single-user operation. 
-i ininame 
Pass the -i initname to the kernel to tell it to run initname as the first program 
rather than the default /sbin/init. 
FILES 

{boot standalone boot program 

/tftpboot/??2222?? | symbolic link to the boot program for a client 

/tftpboot/boot.sun3 —_— programs to boot from the client’s root partition 

/usr/etc/in.tftpd TFTP server 

/vmunix 
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/etc/bootparams 


SEE ALSO 
adb(1), tftp(1), bootparamd(8), init(8), mount(8), ndbootd(8C), rc(8), reboot(8), tftpd(8C), kadb(8S), 


monitor(8S) 


BUGS . | 
On the Sun-2 system, the PROM passes in the default name vmunix, overriding the the boot program’s 


patchable default. 
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NAME 
bootparamd — boot parameter server 

SYNOPSIS 
/usr/etc/rpe.bootparamd [ —d ] 

DESCRIPTION 
bootparamd is a server process that provides information to diskless clients necessary for booting. It con- 
sults the bootparams database. If the client is not found there, or if the Yellow Pages service is not run- 
ning, then the /etc/bootparams file is consulted. 


bootparamd can be invoked either by inetd(8C) or by the user. 


OPTIONS 

-d Display the debugging information. 
FILES 

/etc/bootparams 
SEE ALSO 


bootparams(5), inetd(8C) 
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From: ROTHSCHILD1 Rothschild, Dave 

To? GOINS | Goins, Bill 

ol ore FIELD Field, Don 
ROTHSCHILD1 Rothschild, Dave 

Sub: Remote booting memo 

Bill, 


The following memo describes some of my thoughts regarding the need for remote 
Macintosh booting in the K-12 market. Since I'm not sure who the audience will 
be for this memo, I have broken down into the following sections: 


Ly Summary 


1. Remote Booting 
2. Multi-launch AppleShare aware software 
3. cabling bandwith 


I have one central theme throughout this memo: satisfying the K-12 customer 
need for reduced floppy disk management. Remote booting is an important part 
of satisfying that customer need. 


Schools set up most of their Macintosh computers in labs for increased access. 
Most labs have 20 or more computers. Sometimes the labs have a lab monitor to 
assist students and check out software. Often, a Macintosh startup disk is 
left in each machine. 


Usually, a teacher will schedule one of the open session for their class. For 
example, an English teacher might schedule the lab every Tuesday from 9:30 a.m. 
to 10:15 a.m. When the teacher brings the class in, time is spent handing out 
application software and possibly a teacher developed file for use during the 
session. 


The teacher has 45 minutes total time in the lab. If 15 minutes are spent 
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handing out and collecting application software and data files, only 30 minutes 
are left for instructional use. 


In open labs that students can use during their free time, many schools have 
trouble managing system software and printer drivers. Students bring their own 
disks with old version of printer drivers. Or, someone will walk away or 
damage the startup disk that the school developed. 


The burden of handling all these floppy disks is enough for K-12 customers to 
install network systems. In talking with customers as to why they are 
considering or have purchased network systems (workstations, cabling, printers, 
file servers, etc.) one of the top three reasons will be the need to reduce 
the amount of time spent managing floppy disks. 


To effectively satisfy a customer's need to reduce the amount of time spent 
managing floppy disks, I see a number of requirements. All requirements don't 
have to be available at the same time. Each one comes closer to meeting the 
customer's needs. These requirements are: a 


1. Remote booting 
2. Cable bandwith 
3. Multi-launch AppleShare aware software 


1. Remote Booting 


a) eliminating™s startup d d more importantly system 
get more time for 


Schools have ad j wf managing sy¥ weseftware releases. Student 
access labs with LaserWriters are difficult to manage when students bring in 
their own disks with different system and printer driver versions. I have 
talked to a number of schools that were considering installing file servers to 
help manage their system software. They were under the impression that the 
Macintosh already had remote booting capability 


b) reduce the need to have a full time lab monitor to oversee the lab and 
trouble shoot problems 


2. Cabling Bandwith 


For shared printing, LocalTalk does the job. But for reducing the amount of 
time spent managing floppy disks, LocalTalk is a problem. Class sessions 
should be able to go from cold boot to application software (via finder launch 
from file server) in 2 minutes or less. Competitive pressure is forcing the 3 
minute number down further. 
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Assuming, that a Macintosh workstation only needs to be remote booted once in 
the moftning, then the relevant time is 2 minutes or less for 30 Macintosh 


computers to launch an application from the file server. It is my 
understanding that: Microsoft Word takes about 2 minutes to launch for 25 
Macintosh computers from a Macintosh II AppleShare file server. (We need to be 


testing this configuration with Spin as workstations and one of the new 68030 
machines as a file server.) 


According to various customer reports, a 30 workstation lab of IBM model 30 
computers with a Novell server, takes 30 to 40 seconds to simultaneously launch © 
Word for the IBM workstation. So, our window is closing much below the 2 
minute mark. 


The current 2 minute mark will also be difficult to maintain. Schools 
everywhere are looking for integrated learning systems (ILS). An ILS is 
complete turnkey system that comes with 1500+ lessons which teach students 
basic and higher order thinking skills. The lessons are very graphic, 
animation and sound intensive. Lessons are managed from management software at 
the file server. A lab of 30 students could all be working on different 
lessons at the same time. The result is the network traffic will increase 
throughout a lab session. That combined with larger lessons (larger files, 
300k+) makes a faster cabling system even more important. 


The structure needed toj implem t in K-12 is gre and won't be 
for some time. By str e ‘ost product fi Z, customer 

training, customer systerMdesign a g 
assistance, internal App 


connectors, to the desi implementatjén and support. thernet is a long way 
from this at Apple. By t astave the same Sr Apple II 
workstations on a AppleTalk network. 


3. Multi-launch AppleShare aware software. 


The third component for reducing floppy disk management -is application 
software. Once a customer has remote booted their workstation in a 
"reasonable" time, then they want to launch a application program on the 
server. 


To do this, developers have to modify their applications to be AppleShare aware 
(well behaved on a AppleShare file server) and multi-launch. These developers 
also need to come up with a site/server license and deal with the pricing 
issue. 


Apple II developers are successfully dealing with this issue now. For 


Macintosh developers this will take a lot of work. As far as I know only 
Microsoft Word and Excel are multi-launch and AppleShare aware. Schools really 
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want Microsoft Works. I'm told that this is on the way but timing is unclear. 


II. Computers in the K-12 Market 


The K-12 market has two major market segments: administrative offices and 
classrooms. 


1. Administrative Offices 


All schools have administrative offices. The principal and his or her staff 
are in the school building administrative offices. In school based management 
structure (e.g. a decentralized structure), the principal and staff runs their 
office much the same way as a small business runs their office. Word 
processing - desktop publishing, general productivity tools, accounting tasks, 
attendance, student scheduling, grading, host access, dial up telecommunication 
services are common computing needs. 


Other schools have a more centralized structure whereby a central office 
performs many of the activities listed above. 


2. Classrooms 


Classrooms includ¢ cam : librats i fnteys, and the typical 


Today, the majori 


concentrated, cont. d access. { configuration is 30 
computers arrangd¢d in ¥ : rmat aro ¢ walls of the lab. Often a 
computer coordinator ry é The lab fay be ppen for free access during 
parts of the day led foYclasses quri dther parts of the day. 


In the past, we have sold Apple IIe and Apple IIGS computers in the classroom 
segment and Macintosh computers in the administrative segment. This year we 
expect the mix to be 75% Apple II and 25% Macintosh. Much of the Macintosh 
growth will come from using Macintosh computers in the high school (9-12th 
grade) segment. A number of schools are even using Macintosh in the lower. 
grades. We also expect a portion of the Macintosh increase to come from the 
administrative segment. 


III. Macintosh in the K-12 Classroom Market Segment 
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When customers put Macintosh computers in the classroom, they usually put 15 or 
more in a computer lab. Since schools schedule class sessions in the computer 
lab, you often find 25 Macintosh computers in a lab to accommodate an entire 
class of students. 


For reference purpose, I'll describe a customer situation that describes the 
need for remote Macintosh booting. Lincoln High School in Stockton, California 
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has 25 dual drive (2 floppies) Macintosh SE computers in one room. Some of the 
Macintosh computers are arranged in a u-shape around the walls while the 
others are in a square shaped group of 4 desks in the middle of the room. Each 
group of four share an ImageWriter II printer (the most commonly sold printer 
in the K-12 classroom segment). 


Each Macintosh has a pre-configured startup disk in one of the drives. The 
disk has the latest system, finder and print drivers, as well as special 
utilities like Pyro. A lab monitor is available at all times to help students 
and to check out software from the software library located in the lab. 


Most of the time the lab is scheduled for class use. Teachers sign up on the 
lab calender to bring their class to the lab during a certain period of the 
school day. Unscheduled time is available for walk-in students. 


Currently, Lincoln High School would like to move away from having to manage 
floppy disks. It takes to much time to manage all the floppies. The startup 
disks often "walk away" or get erased. Students sometimes copy other software 
onto the disks. Also, the software is a hassle to check out and control. A 
class typically has 50 minutes in a lab; if 15 of those minutes are spent 
managing floppy disks (not an uncommon amount of time) then a whole lot of 
instructional time is lost. (These are the same needs that we see in the Apple 
II computer labs). 


IV. Administrators andj Test Scores 
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Parents and legislators 
test scores. 


Consequently, they are 
purchased, those administra 
maximum use of those computers. They will pay extra for products that increase 
the amount of time on computers and (hopefully) result in improved test scores. 


Many school administrators think that computers are a tool which can help to 
increase test scores. To use the tools, students need access. Reducing the 
amount of time spent managing floppy disks increases instructional access to 
these computer tools. Remote booting is an important piece to providing 
increased access and improved test scores. 


* * * * FHF HK KK KK KK KK KIKI KK IK IKK IK KKK IKK KKK IKKE KKK KKK KKEKK KKK KKK 


I hope this memo has been helpful. Please feel free to link me if you would 
like any clarifications. 


Regards, 
Dave. 
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Gestalt ERS 


Carl Hewitt 
Brian McGhie 


Summary 


The Gestalt function provides a clean and efficient method for applications to re- 
quest information from the operating system. It is intended to supersede the current 
implementation of SysEnvirons as the standard method of determining aspects of the 
operating environment. Gestalt is designed so that applications can access information as 
they need it, without having to request more than what is necessary. It also gives the op- 
erating system a degree of flexibility in deciding how the information should be deter- 
mined and/or stored. The primary design criteria is simplicity. Anything which 
complicates the model goes against the original goal of Gestalt. The design also enables 
Gestalt to be used as a simple IPC mechanism. 


Description 
Informatior is 4¢ces qugh the'Gestalt functigh by/using function codes. An 
application calls ber of the informAtion fhat it needs, and Gestalt 


returns the infor 


everything currently retuened-bY SysEnvirons, atso-allows new function codes to be 
added or changed externally (e.g. at init time). This is a great benefit to applications, 
since it allows them to easily determine what features are available in the current 
ROM/System environment, and it’s a benefit to Apple, since we don’t have to update the 
Gestalt function to add new function codes. To illustrate, Jackson Pollack could register 
itself with Gestalt at init time. Applications could then determine if Jackson Pollack is 
present without the system knowing about Jackson Pollack. 


Another benefit of this function is that it gives third-party developers a 
“primative” way to provide access to their software from other applications (a.k.a. Inter- 
Process Communication). To provide this service to third-parties would require arbitration 
on function codes, which DTS has informally expressed a willingness to do. 


Operation 


When an application calls the Gestalt function, it passes Gestalt a function code 
and is provided with a result (long word) and an error code (word). For many situations, 
this result could be stored in a bit-string for Boolean values or in a relocatable table for 
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long values. However, in some situations, determining the result may require code to be 
executed at the time the information is requested. To provide for this, the Gestalt 
function can call a procedure to determine the result that is returned to the calling 
application. 


To differentiate between the results of function codes that need to execute code, 
and those that can be stored, Gestalt divides the function code results into different types. 
A function code result can fall into one of the following categories: 


e Boolean 
Long 
e Procedure Determined 
A piece of information such as whether a machine has Color Quickdraw, for 


example, would fall into the Boolean category. A piece of information that would fall 
into the Procedure category would be a function that returned the working directory. - 


Gestalt Interface 


The following is a descyptionof the Gestalt infterface: 


FUNCTION Gestalt (code: LONGANT; VAR fresult]: LONGINT) : OSErr; 
The Gestalt function takes a code and a pointer to a long word. On return, it 

provides an error code, and a result in the location pointed to by result. If there was no 

error, the result will contain the appropriate information, otherwise it will always return 


a zero for a result. 


Assembly-language note: The trap number and interface for the Gestalt function are as 
follows: 


_Gestalt SAOAD 
On Entry: DO = code 

AO = ptr to long word for result 
On Exit: DO = error code 
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Advanced Routines 


The following routines are for advanced programmers who wish to add, change, or 
remove Gestalt function codes. 


FUNCTION NewGestalt (code: LONGINT; newValue: LONGINT) : OSErr; 


‘FUNCTION AlterGestalt (code: LONGINT; newValue: LONGINT) :;: 
OSETrr? 


FUNCTION RemoveGestalt (code: LONGINT; VAR oldValue: LONGINT) 
OSErr> 


The NewGestalt function will associate the specified value with the given unused code in 
future calls to Gestalt. If the function code has already been assigned a number, 
NewGestalt will zero the result and return an error. 


The AlterGestaJ]t function changes the value associated with a particular function code 


to the specified new v ction ¢ode exist, AlterGestalt 
will zero the resulf and re Oo error codk 

The RemoveGestdalt entries for fuxctionfcodes. The value associated 
with the function cod d is returned in th¢ long pointed to by oldValue 


the returned andjthe procedur¢ is not galled. 


Assembly-language note: The calling conventions and interfaces tor the advanced 
Gestalt functions are as follows: 


Trap Macro: 
_Gestalt ,GNew (adds a function code) 
_Gestalt ,GAlter (changes value associated with a function code) 
_Gestalt ,GRemove (removes a function code) 


GNew and GAlter: 


On Entry: D0 = code (long word) 
_  AO= new value to be associated with code 
On Exit: DO = error code 
GRemove: 
On Entry: D0 = code 
AO = ptr to long word for result 
On Exit: DO = error code 


AO = ptr to long word for result 
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Pre-Defined Function Codes 


Gestalt predefines several function codes to provide the same information as the 
SysEnvirons utility, and adds a few more (little thought has gone into the possible codes 
that we should have here-these codes are trivial to add or change). The following 
function codes are pre-defined by Gestalt: 


CONST GVersion = 0; { Gestalt version } 
CQDExists = $20; { CQD exists? } 
GMachType = $4000; { machine type } 
GSystemVers = $4001; { system version } 
GProcessor = $4002; { processor type } 
GKeyboardType = $4003; { keyboard type } 
GFPUType = $4004; { FPU type } 

GMMUT ype = $4005; { MMU type } 
GRAMSize = $4006; { RAM size } 
GROMSize = $4007; { ROM size } 
GAtDrvrVersNum = { Atalk version } 
GSysVRe ENpr = 


CONST GVersion = 0; { Gestalt version } 


The CQDExists code returns a Boolean value indicating whether Color Quickdraw is 
present in ROM. 


CONST CQDExists 
GCQDNotPresent 


$20; { CQD exists? } 
OF { CQD not present } 


The GMachType code returns a value indicating the type of machine currently being run 
on. 


CONST GMachType = $4000; { machine type } 
GUnknownMachine = 0; { New Macintosh } 
GClassic = le { Mac 128K } 
GMacxL = 2; { Mac XL } 
~GMac512KE =, oF { Mac 512K Enhanced } 
GMacPlus = 4; { Mac Plus } 
GMacSE © =. oF { Mac SE } 
GMacII = 6; { Mac II } 
GMacIIx = 7; { Mac IIx } 
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GMacIIxc 
GMacSE030 


8; { Mac IIxc } 
oe { Mac SE 030 } 


The GSystemVers code returns the version number of the System file represented as two 
- byte-long number. For example, this function would return $0604 when running under 
System 6.0.4. The upper two bytes of the result should be ignored. 


CONST GSystemVers = $4001; { system version } 
The GProcessor function code reveals the type of processor currently being run on. 


CONST GProcessor 
GUnknownCPU 
G68000 
G68010 
G68020 
G68030 

G68040 


$4002; { processor type } 


loud’ t uw wou 


CONST GKeypoard = fyboard type } 
0; nknown keyboard } 
a Mac keyboard } 
z23 Mac kbd and keypad } 
33 Mac Plus keyboard } 
4; Apple extended kbd } 
SF Apple Std ADB kbd } 
The GFPUType functi s the type of flaatink-point coprocessor installed, if 
any. 
CONST GFPUType = $4004; { FPU type } 
GUnknownFPU =. -1% 
GNoFPU =e 
G68881 = 2; 
G68882 = 3; 


The GMMUType code returns the type of memory-management unit present, if any. 


CONST GMMUT ype = $4005; { MMU type } 
GUnknownMMU = - 03 
GNoOMMU a de 
G68851 = 2; 
G68030MMU = 3; 


The GRAMS ize code will cause Gestalt to return the number of bytes of RAM currently 
installed. | 


CONST GRAMSize = $4006; { RAM size } 
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The GROMSize code will cause Gestalt to return the number of bytes of ROM currently 
installed. 


CONST GROMSize = $4007; { ROM size } 


The GAtDrvrVersNum function code will return the version number of the AppleTalk 
driver currently installed. The three high bytes of the result should be ignored. 


CONST GAtDrvrVersNum = $14000;  { Atalk version } 


The GSysVRefNum function code will return the working directory ID of the folder 
containing the System file (the “blessed folder”). The high word of the result should be 
ignored. 


CONST GSysVRefNum = $14001; { system vrefnum } 
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MacVM 


Virtual Memory for Macintosh 


What MacVM Is 


MacVM is system software that allows any Macintosh equipped with a MMU to extend the 
perceived amount of RAM available. Memory can be extended up to 14 Meg on existing systems, 
and up to 1 Gig on systems with 32-bit ROMs. 

One cost of this extra memory is the use of an equivalent amount of storage on a backing 
device. Typically this would be a SCSI hard disk, although it could include other types of storage 
devices as well. 7 

The other cost of using MacVM is a loss of speed. This ranges from unnoticeable when less 
than 2 times the physical memory (i.e. the “real” amount of RAM) is used to severe degradation in 
performance when virtual memory is heavily taxed. Two caveats are that in the former condition 
the Mac might be even faster than before—due to a faster trap dispatcher, and that the latter 
condition is difficult to cause using Mac applications. 
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MacVYM is not a cure-all for small amounts of RAM, piggy applications,.or bloated system 
software. The most obvious reason for this. is that the machifies most in néed of virtual memory, 
the MacPlus and SE, cannot run MacVM Ssitice-they do nét’(and can not) haye MMUs. In addition, — 


a MaclII must be retrofitted with a 68851. MMU inorder to runit., e 

MacVM is not a complete virtual memory solution, in the classical sense. It does not provide 
for hardware protection. It does tiot support '‘multipleaddress spagés. It does not explicitly solve 
MultiFinder fragmentation probléms, except to ease them by previding.:more memory. 

MacVM is not a solution for users that run existing intelligent NuBus cards, such as Apple 
smart cards using MR-DOS, ‘and (probably) third-party DMAcards. | 


User Interface 


To use MacVM, bring up the MacVM panel in the control panel. Use the check box to turn 
MacVM on and off. Use the slider to determine how much virtual memory to allow. The status 
box tells whether MacVM has been installed, or else the reason it has not been. 

The maximum amount of virtual memory in a 24-bit machine is 14 Meg. Unfortunately, for 
each NuBus card the machine has, it loses 1 Meg of virtual space. For example, a Mac II that has 2 
video cards and an Ethernet card has a maximum of 11 Meg available. This presents a small user 
interface problem—how do users understand available slots vs. available memory? 


* e.g. RAMDisks, etc. Basically, any device that allows block-level access can be used. This disallows VM with 
an AppleShare volume as a paging device. 


Apple Confidential Page 1 


Friday, April 7, 1989 MacVM ERS Draft 2 


Canonical VM Description 


The virtual memory scheme implemented by MacVM is a demand-paged scheme using the 
Motorola 68030 or 68020 with 68851 PMMU. The 32-bit address space is mapped by a 3 level 
page table. The highest level divides the space into 256 16 Meg segments. The first of these is 
actually the entire 24-bit address space. The other 255 segments are left untouched; right now they 
are only used to map through slots, ROM, and I/O in 32-bit mode. 

The first 16 Meg is broken down into 16 1 Meg segments. 2 of these segments, those 
corresponding to ROM (segment 8) and I/O space (segment 15), must be mapped through; they 
cannot be used for paging. This also applies to the 1 Meg chunks used by NuBus for slots in which 
active cards reside. 

However, the first 8 Meg and each Meg that corresponds to a card-less slot is usable for virtual 
memory. Each of these 1 Meg segments is broken down into 256 pages of size 4K. 

These pages are shuttled between RAM and the backing store (i.e. the virtual memory file) 
using a modified CLOCK page replacement algorithm. The only part of CLOCK not implemented 
is the asynchronous writing of dirty pages; it is too expensive without DMA. 

MacVM provides primitives for locking a given range of virtual memory into physical 
memory. It also provides a primitive to allow the caller to tell MacVM he no longer is using a 
range of memory. 

MacVM runs all user-level code, all code not-executed as the result of an exception, in user 
mode. This is necessary in order to prevent the machine from locking Up if it bus errors onto a 
stack that is itself paged out. MacVM keeps a supervisor stack that is locked into physical 
memory. Since all bus error exception-frames-are-thrown/on this’stack; it'ig-not necessary to lock 
down all of the user stacks. Nate that this-still implies that.¢ither no stack*switching can go on at 


interrupt time, or else that these stacks must also"be locked down. 
Reentrancy 


The basic mechanism for MacVM is, fairly straightforward. The tricky part is how to handle page 
faults at interrupt time. The basic problem is that the’SCSI driver is not'reentrant. But, to handle 
interrupt-driven page faults it ‘must be:~-" < ; 


There are two solutions to this.problem, The first is simply.to.change the SCSI Manager to be 
reentrant. This will happen, in time. The new Asynchronous SCSI Manager will, in fact, be 
reentrant. In addition, it is possible for MacVM to patch old SCSI drivers in order to put a 
reentrant layer on top of them. The problem is that applications that use the SCSI Manager directly 
cannot be handled by this scheme. 

Another solution is to defer all user code while using the driver responsible for the backing 
volume. The idea here is that only user code can cause page faults. Since low memory and the 
system heap is locked into physical memory, only application memory (as well as memory above 
BufPtr) can cause page faults. Of course, we define user code as any code that may touch this 
memory. 
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User code includes the following: 


* VBL Tasks: These are scheduled at interrupt time, yet VBLs installed by an application have 
full access to the application’s code and data. Ideally, only the application VBLs will be 
deferred. However, implementation details (i.e. ease of programming) may cause all VBL 
tasks to be deferred. In either we case we will guarantee that cursor code is never deferred, 
so that the cursor does not jump around the screen while paging. 

¢ Slot VBL Tasks: These are treated in the same fashion as are VBL tasks. 

¢ Time Manager Tasks: These are treated in the same fashion as are VBL tasks. 

¢ Completion Routines: Code that is run as a completion routine for a driver may very well be 
run indirectly as the result of an interrupt. Therefore, it might run in the middle of the 
paging driver. . . 

¢ LAP Protocol Handlers: As with VBL tasks, we only really need to worry about application 
protocol handlers. However, we must be more careful in this case because system protocol 
handlers may turn around and call user code at higher levels (e.g. socket listeners). 


The solution we will use is hybrid. At MacVM initialization time we will determine whether or not 
the driver for the backing volume uses the new SCSI Manager. If not, we will continue to defer 
user code while in the driver. If so, we will let the user code run always, since the driver can deal 
with the reentrancy. Applications that use the néw'SCSI Manager directly should work well. 
However, those that use the the old interface must;be treated with kid gloves; they must be locked 
in memory while doing SCSI transactions. : 

We will optimize in the “reeneraricy-al 
in memory longer. ne Sean 


; : AYRE ARERR ARE RE RARER ERROR RR OEE “ 
atlowed” case by keeping pages touched at interrupt level 
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Other Atrocities 


MacVM takes over “unused” space between $900000 and $F00Q00. Each of these six 1 Meg 
chunks is reserved by a Nubus card in a corréspondirg slot. At initialization time MacVM makes a 
SCkCardStat call to the slot manager, and aSsumes that the slot’s Meg As free is it returns a 
smCkStatusErr error. Later ort,. MacVM patches erisure that the chunks that are used are encased 
in large non-relocatable blocks itithe.heap.feithier the MultiFinder-heap or the application heap). 


“Where in the Mac are we?”’ 


MacVM is initialized as MacsBug. It sets up the MMU and the virtual memory file, remaps 
memory into the virtual space, and then installs its patches. Then, it continues the Mac boot 
sequence, loading the real MacsBug (if it exists) as the Disassembler. 

MacVM runs below all other software, except the driver for the backing volume (and 
whatever code upon which it is dependent). 
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Dependencies 


The following dependencies exist in MacVM currently, but should be removed from the final 
version: 


* MacVM depends on trap CountADBs called from location $40807726 in the ROM. It needs 
to find a trap called after system patches have been installed. 

° MacVM tests to see if MultiFinder is around by looking at low memory location $B7C. 
There are (poor) reasons for this, but it will be changed. 

¢ MacVM assumes that its backing file is located on an HFS volume (as opposed to an external 
file system). Actually, it could run on an external file system, if it had an underlying 
block-level driver and supported the HFS vector MapFBlock. 


$A Most Frequently Asked Questions 


Q: Why is it so slow? 

A: Because it’s VM, not PM. Actually, about 1/3 of MacVM currently is debugging code. 
When this gets pulled it should be significantly smaller and faster. We will also be adding more 
optimizations. Thanks to Gary Davidian we may actually get MacVM running faster than non-VM 
while the machine is not paging. aoa 


Q: Why do I get dropped into MacsBug so oftén, with strange messages? | 

A: This is the 1/3 of Mac¥M that is debugging code {see the previous.question). Please let us 
know (AppleLink, InterMail, AppleShare Drop Box...anything but VoiceMaily’ what these 
messages say. With the current vetsiori‘of MacV.M (0.07) you should only seé these under the 
influence of AppleTalk. te ES pe og 


Q: Will I have tons more virtual memory with the new 32-bit ROMs? 
A: Not unless you have moré'RAM and nore disk space. Tufning 2/Meg of RAM into 80 Meg 


of virtual memory will run slower than a Lisa on Quaaludes. 


Q: Why is the MacVM Control Panel so goofy looking? { 


"a: &, ry 


A: Because our OS fiends would-taughrat us if we spent tittié Gi it. To quote a well known OS 
figure, “User Interface is last on my list of priorities.” 


Q: Who can I talk to about all my MacVM problems, questions, suggestions, hopes, fears, and 
desires? 
A: Darin Adler @ 4-3621 and Joe Buczek @ 4-6305. 


Q: What happened to the other 5 questions? 
A: Phil got sleepy. Besides there are only 4 missing. 


Open Issues 
This section is still open. 
New Calls 


This section and following sections describe the trap interface to Mac VM. These services will be 


* Ask John Meier for the reference. 
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used by drivers and other code that need to lock pages into memory or know about physical 
addresses. Any code using these services is responsible for “undoing” any of the effects caused 
(for example, MacVM will not automatically unlock pages that have been locked down). The 
result of not undoing these effects in a timely fashion will cause poor performance and, in the 
worst case, could cause the system to run out of physical memory. 


MacVM memory services are entered through a common trap with register D0.W containing a 


dispatch code to select the service desired. Appropriate MPW glue code will be provided to allow 
symbolic calls for each function. The trap word is defined as follows: 


_MemoryDispatch OPWORD $AO0SC_ ; dispatch for all VM calls 


(Note that these calls are not specific to VM and may exist in the future independent of the 
presence or absence of a virtual memory system.) 
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Disabling Pages from Being Swapped 
This function should be used by drivers that access user data buffers at interrupt level, whether 


transferring data to or from them. Calling HoldMemory on the appropriate memory ranges 
prevents them from causing page faults at interrupt level. 


OSErr HoldMemory(void* address, unsigned long count); 


In: 
DO.W. = selector (0 for HoldMemory) 
Di.lL = count 
AO = address 
Out: 
DO.W = error code 


Make the portion of the address space starting with address and continuing for count bytes 

resident in real memory and ineligible for paging. The contents of the specified range of virtual 
addresses can move in real memory, but they are-gyaranteed to always be in real memory when 
accessed (i.e., no page fault carrresult'by "accessing the addresses): Locking is applied to whole 


> 


pages of the virtual address space. 


The address of the beginning of the range. of virtual address épace to be locked: If the specified 
address is not on a page boundary,:it'will be rotinded down to the nearest page boundary. 


The size in bytes of the range of virtual address space to be locked,f the specified is not an 
integral multiple of the system page size, it will be rounded up to,the next whole multiple of page 
size. f *% i ; : 


Returns: 7 
parameErr ie nase 
notEnoughPhysicalMemoryerr 
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Enabling Locked Pages to Swap Again 


The UnholdMemory function should be called by drivers upon completion of an [/O request before 
jumping to j[ODone. 


OSErr UnholdMemory(void* address, unsigned long count); 


In: 
DO.W = selector (1 for UnholdMemory) 
Di.L = count 
AO = address 
Out: 
DO.W = error code 


Make the portion of the address space starting with address and continuing for count bytes eligible 
for paging again. Unlocking is applied to whole pages of the virtual address space. This facility 
reverses the effects of HoldMemory. 


Returns: - 
° : 2 - ’ ‘. 
: 3 S % 
3 : : 
3 : 2 Hy 
paramerr : 4 ; % 
> 3 ° % 
*. * ° 4 
3 * s sd 
3 : 2 ot 
2 geereseerrveerveeerererveereerererrend 3 e 
3 3 : es s 
3 2 2 : Jo 
3 3 : 
3 3 3 
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Disabling Movement of Pages in Physical Memory 


This function is used by drivers whenever hardware other than the Mac CPU is transferring data to 
or from user buffers, such as any NuBus master peripheral card or DMA hardware. This function 
both prevents paging and physical relocation of a specified memory area. In turn, this enables the 
physical addresses of a memory area to be exported to the non-CPU hardware. Typically, this 
service would be used for the duration of a single I/O request, however, data structures that are 
permanently shared between driver code and a NuBus master could be frozen using this service. 


OSErr LockMemory(void* address, unsigned long count); 


In: 
DO.W = selector (2 for LockMemory) 
Di.L = count 
AQ = address 
Out: 
DO.W = error code 


Make the portion of the address-space-starting ‘with address-and.continuing-for-count bytes 
immovable in real memory arid ineligible for paging. Th¢ contents of the specified range of virtual 
addresses may be moved in réal memory..to.a.more convenient_location.during the kernel call 
operation, but on completion, the contents of the specified range of virtual addresses will be 
resident and will not move in realimétnory. Freezing is applied to whole pages of the virtual 
address space. This facility is'useful for.drivers arid other applications that-may need to handle 
interrupts and I/O devices. 2. ‘ ‘ é. ¢ 

Pages frozen in memory are marked as non-cacheable. The main reason to “disable movement 
of pages in physical memory’ is to.translate; virtual addreses to physical addresses. This translation 
is needed by bus masters which must write,to memory in the physical address space. To avoid 
stale data, the memory is marked non-cacheable. (Note: a callér must flush the cache prior to use). — 


os 


Returns: 
paramerr 
notEnoughPhysicalMemoryerr 
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Forcing Pages to Occupy Physically Contiguous Physical Pages 


The LockMemoryContiguous service is used by driver and NuBus master or driver and DMA . 
hardware combinations where the non-CPU device accessing memory is unable to handle 
physically discontiguous data transfers. This service may also be used when handling physically 
discontiguous data transfers is possible, but causes performance problems. 


OSErr LockMemoryContiguous(void* address, unsigned long count); 


In: 
DO.W = selector (4 for LockMemoryContiguous) 
Di... = count 
AO = address 


Out: 
DO.W = error code 


This is exactly like LockMemory, except that it attempts to get a contiguous block of physical 
memory associated with the logical address range.specified. 


Returns: : j ; 
NOtENoughPhysicalMeEMOryEP _eecwcmmesneg oe € 


cannotMakeContiguousErr:  *~ ae 


3 


4 , . 
BARRO ARR O ROAR ROR ARE, 
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Enabling Movement of Pages in Physical Memory 


OSErr UnlockMemory(void* address, unsigned long count); 


In: 
DO.W = selector (3 for UnilockMemory) 
D1.L. = count 
AO = address 
Out: 
DO.W = error code 


Make the portion of the address space starting with address and continuing for count bytes 
movable in real memory and eligible for paging again. Unfreezing is applied to whole pages of the 
virtual address space. Unfrozen pages are marked as cacheable. This facility reverses the effects 
of LockMemory (or LockMemoryContiguous) discussed above. 


Returns: 
paramErr oe 
n re) t Li 0 C kK e d E r r cere: ich Glasmseitacinaee 


Seceeawreveresesceeeeverererereerereer es 


wee eretetetetedteeleteel, 
re 
- 


toteratatetetatetetels! 
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Getting Page Mapping Information 


The GetPhysical function provides drivers with actual physical memory addresses of pages in a 
specified logical address range. This information is necessary to permit non-CPU devices to access 
memory mapped by the CPU. Mapping information is needed to enable data transfers by non-CPU 
devices to physically discontiguous memory via external software or hardware mapping 
mechanisms. 


struct MemoryBlock 


{ 
void* address; /* start of block */ 


unsigned long count; /* size of block */ 


’ 


*define defaultPhysicalEntryCount 8 /* default * of physical blocks in table */ 
struct LogicalToPhysicalT able 
( 
MemoryBIock logical; © © pemmmnecnencmmmneel A TOGICAl DIGCK EL nineneentinn 
MemoryBlock physicalldefaultPhysicalentryfount];:/* equivalent blocks */ 


B 
: 
} ; 3 ” 
2 Secu RY 2 ALA AERARE RAPE AEREAREE RE PREEESY a 
, 3 ge Penewcevereveacerreresevewrreoereredt : “we ee ca 
3 3 : “ o es 


OSErr GetPhysical(Logi calToRhy sicaTTable* addresses, ~~” 
unsigned long* physicalEmtryCount); *s, 


In: ses 
DO.W = selector (5 for GetPhysical) : / i 
D1. = physicalEntryCount (number of entriegfor physi¢gal in table) 


2 


AO = addresses (pointer.to TranstationT able) ; 
Out: Neem eens eee” mere 

DO.W = error code 

D1i.L = number of pairs returned 


Translate virtual addresses to corresponding physical addresses. Passed into the routine is a 
parameter block with a table to store physical address/count pairs and the size of the translation 
table. The translation table is an array of ordered pairs (address and count). GetPhysical will 
translate up to the size of the table or until the translation is completed, whichever comes first. 

If GetPhysical is called with a table size of zero, the number of table entries necessary to 
translate the entire address range will be returned. 

Upon exit, the virtual information will be updated to indicate the next virtual address and the 
number of bytes left to translate. If the translation is incomplete, the same translation table can 
again be passed to GetPhysical to continue the translation of the remaining addresses. The return 
value from the call will indicate the number of physical address/count pairs actually placed in the 
translation table. 

The translation parameter block consists of two different elements: the virtual information and 
the physical translation table. The virtual information is stored as an ordered pair of address and 
count. The physical translation table is an array of address and count pairs which define sections of 
physical memory representing the virtual address range input parameter. 
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On exit, the virtual information is updated to reflect the address range which was not 
translated. The virtual address field will contain the next virtual address to be translated, and the 
virtual count field will have the number of bytes left to be translated. 

The parameter count is used to indicate the size of the translation table array. The actual count 
value is the number of physical ordered pairs that can be returned in the translation table. Passing 
in the size of the table allows the calling software to adjust the table size to fit its application. 
Calling software can then make tradeoffs between memory and complexity versus the overhead 
for multiple calls. 

Upon return, the physicalEntryCount parameter contains the number address/count pairs 
which were filled into the translation table. In addition, if physicalEntryCount contained zero, the 
total number of entries required to map the entire logical space is returned (and the contents of the 
table are unchanged). The return value for GetPhysical is the number of address/count pairs which 
were filled into the translation table. A value less than zero indicates an error. 


Returns: 
parameErr 
notLockedErr 


An example of using GetPhysjcal.in.Ci  ? 


: 
; 
? 
3 


3 


OSErr error; Ree ; "fatal eid 
translation tahie */ 


LogicalToPhysicalTable table; mee 


table.logical.address = buff ér Addr SS}. 1% vietual address */ ye 


table.logical.count = bufferSizes’ «7 bytes fp buffer */ 
while (table.logical.count‘i= 0)" 1% more bytes to deal'with?*/ 
( t f f : ¢ ? 


unsigned long numPhysicalBlocks"="éef aultPhysicalentryCount; | 
error = GetPhysical(&tablé;&naumPhysicalBlocks); seal 
DoSomething(&table, numPhysicalBlocks); 

} 
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Getting System Memory Configuration Information 


struct SystemMemorylInfo 
{ 
long logicalMemorySize; /* * of bytes of logical memory */ 
/* (not necessarily contiguous) */ 
long physicalMemorySize; /* * of bytes of physical memory */ 
long pageSize; /* size of each page in memory */ 


° 
J 


OSErr GetSystemMemorylnfo(SystemMemoryinfo* info); 


In: 
DO.W = selector (6 for GetMemoryinfo) 
AO = info (pointer to Memoryinfo) 
Out: 


DO.W = error code conway > noErr forthe time belnore 
Get memory management infotmation. about.the. ad states GetSystemMemorylnio} +eturns the 


logical memory size (which is equal to the total amount of ‘Swapping space), thé physical memory 
size (actual RAM), and the page size: “This information can be used to pales an appucanen more _ 


a 
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Interrupt Handling 


During the time that the Macintosh is handling a page fault, it is critical that no other page faults 
occur. Since no other work is explicitly done by the system during the handling of a page fault, the 
only code that can cause this to occur is code that runs as a result of an interrupt. 


The HoldMemory function must be called on buffers or code that are to be referenced by any 
interrupt service routine. This call must be made at non-interrupt level since the MemoryDispatch 
calls can cause movement of memory and possible I/O. 


The use of ProcPtr’s in specifying IOCompletion routines, socket listeners, etc., makes it 
impossible for drivers to know the location and size of all code or buffers that may be referenced 
when invoking these routines. However, these routines must still be restricted to being referenced 
at a “safe” time when paging is not currently in progress. Because the locations of all needed pages 
cannot be known, an alternate strategy is used to prevent a fatal double page fault condition. 


The _DeferUserFn trap is provided to allow interrupt service routines to call code that may cause 
page faults at a “‘safe” time. This trap determines if the call may be made immediately and does so 
if possible. If a page fault is in progress, the routine address and its parameter are saved and the 
calling of the routine is deferred until page faultS“ate again permitted. | 


OSErr DeferUserFn(ProcPtr, void* argument); 


AQ = address of the routine to call... “, 
DO.L = argument to pass ta.the*specifiéd function 


Out: 
DO.W = error code 


Returns: 
cannotDefererr 


The routine specified is called with register AO containing the value of the “argument” parameter 
to the DeferUserFn call. Note that the routine may be called immediately (before returning to the 


caller of DeferUserFn). 
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Pascal summary for all of the above: 


FUNCTION HoldMemory(address: Ptr, count: LONGINT): OSErr; 
FUNCTION UnholdMemory(address: Ptr, count: LONGINT): OSErr; 


FUNCTION LockMemory(address: Ptr, count: LONGINT): OSErr; 
FUNCTION LockMemoryContiguous(address: Ptr, count: LONGINT): OSErr; 
FUNCTION UnlockMemory(address: Ptr, count: LONGINT): OSErr; 


TYPE 
MemoryBlock = 
RECORD 
address : Ptr; (start of block 
count :LONGINT; {size of block) 
END; 


CONST 
defaultPhysicalEntryCount | = 8. (default = éf pysteal: DTOCRS ‘ttabtet 


: 


3 Fy 
g é 
$ 3 : 
$ grove reeeeverevceveccerveereverrwseed : JAP RPARA SABRE RAR SERS RE RE ANIA NSD 
3 2 3 ” 
3 3 2 eS 
2 2 : ra 
3 3 Fi 3 
: : 
weer us, Roane. 


Reg cal ioPnystegil saieer SOP er ee 
logical “MemoryBlock; | “ : é ‘ 
physical : ARRAY [1. derauntOnysicaltntryCouht- 1] OF remporyB lock, 
END; : *% ; : é f 


FUNCTION GetPhysical(VAR ipdaresdes: LegicalToptystcal Table 
VAR physicalentryCount: ‘LONGINF?: OSErr; 


TYPE 
Memorylinfo = 
RECORD 
logicalMemorySize :LONGINT; (* of bytes of logical memory) 
{(not necessarily contiguous)) 
physicalMemorySize : LONGINT; (* of bytes of physical memory) 
pageSize : LONGINT; (size of each page in memory) 
logicalAddressBits : INTEGER; {* of bits in logical address) 
physicalAddressBits : INTEGER; (* of bits in physical address} 
END; 


FUNCTION GetSystemMemoryinfo( VAR info: Memoryinfo): OSErr; 


FUNCTION DeferUserFni(function: ProcPtr; argument: Ptr): OSErr; 
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Introduction 


This ERS pertains to the development of MultiFinder 7.0, with the notable exception of the 
Interprocess Communication Facility (IPC), which is documented by Jay Moreland in a separate ERS. 
Several of the items in this ERS have already been introduced in an intermediate version describing 
MultiFinder 6.1 (which was released to APDA in January 1989). 

There are significant changes to the general operation of MultiFinder that will not be readily 
perceived by the developer or the user, but will help provide a substantial basis for future development by 
Apple System Software and third party developers. Namely, they are the fact that it will be 32-bit clean, 
and that it will provide support for MacVM. 

Desktop management was enhanced with a feature ("Set Aside “) to reduce clutter by temporarily 
hiding unused applications. Tentatively, MultiFinder 7.0 will also include a feature dubbed “hibernation” 
that supports a practical MultiFinder-only scenario for machines with less than one megabyte of RAM. 
Both features are currently under review by the Blue Interface Group. 

Several changes were made to accommodate the evolution of the Finder. They include support 
for customized smail icons, more control of the Pic menu, and desk accessories being launched in 
individual layers. 

The multiprocessing } inodel was Tefined i in a | number of areas. First, ‘multiple ‘packground 
applications can now be launched at MultiFinder startup time. Second, developers’ applications now have 
greater control over their owri exeeution-and-that-of applications they may Taunch. Fhird, the temporary 
memory, scheme was c10u: ileu Gus . facilitate general use, without placing spegiai requirements on the 
application. 

There are several proposed, changes that were unfortunately gémoted to the "second string" as 
realistic time constraints were layed out. There is nothing i in the wish [iSt that will not some day be 
accomplished. However, for Big Bang they will be implemented only when, the primary projects have been 
safely completed. 

Last, but not least, a waming. Aithough some items fromthe MultiFinder 6.1 ERS remain 
accurate, there have been 4. few changes. ere giscard that document! 


Se, 
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General/Operational 


¢ 32-Bit Cleanliness 
MuttiFinder 7.0 will operate in a 32-bit clean manner. Currently, there are many violations primarily 
in MultiFinder's intimate knowledge of the 24-bit memory manager. 

Most changes will be intemal and therefore of no concer outside MultiFinder. There are a few 
exceptions in that the current programmatic interface itself is not 32-bit clean. A complete list of these 
exceptions and their resolutions will be forthcoming. 

The result is that MultiFinder 7.0 will support either a 24- or 32-bit environment, but not in a so- 
called “mixed mode” (a scenario in which 24-bit and 32-bit applications could be executed concurrently). 
This is consistent with the Memory Manager proposal for Big Bang. 


¢ Virtual Memory Support 
To be determined. 


User Interface Changes 


¢ Apple Menu Rearranged 

The list of active applications will be moved close to the top of the Apple menu. Currently, this list 
is near the bottom, which is inconvenient. 

Also, a "Set Aside” menu item will be added in a position to be determined (see Set Aside below). 


e Set Aside ; i pe 

Opening several windows from several rusining applications has a tendency} 10 clutter the 
desktop, making it difficult fok the.user-te distinguish windgws associated with:any given application. 
Currently, the only recourse is forthe user.ta., ier "eth ragiza, and move windows; “or to temporarily quit 
some application. 

MultiFinder 7.0 introduces a.new. feature, ‘Called "Set Aside”, that makes it easy to hide all windows 
associated with an application. The application remains open, but its. windows become hidden until the 
next time they are needed. Thi’is strictly a convenience for the user, and Fequires no effort by the 
application(s) in question. tt is backward compatible with almost all; applications that work under 
MultiFinder. 

There will be several methods to hide and recover the current soptcaton Details to be 
determined by the Biue Intettace Group. < i 
¢ Support for MultiFinder-Oniy “System (aka Hibernation) 

To be determined by the Blue Interface Group whether this will be included. 


« Other Human Interface Issues 
To be determined by the Biue Interface Group. Maybe nothing. 


¢ Multiple Background Applications Launched at Startup 

Under MultiFinder 7.0, multiple background applications can be made to launch automatically and 
as soon as possible in the MultiFinder startup sequence. Currently, the only such application is the 
Backgrounder; others must be launched by support applications. This is inconvenient. 

To be launched at MultiFinder startup, an application need only be located in a new folder, called 
Background Folder, that in tum is located in the system folder. MultiFinder searches Background Folder 
and attempts to launch any application it finds. 

This feature is backward compatible with startup disks that don't have the new folder. In this case, 
MultiFinder attempts to launch the Backgrounder from the System Folder directly. If the Background 
Folder does exist and contain applications, however, it should also include the Backgrounder (otherwise 
Backgrounder will not be launched). 
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New Services 


¢ Small Icon Support 

Applications will be able to define a “small icon” resource that will represent the application in the 
Apple menu and in the right end of the menu bar. Currently, this representation is a shrunken version of 
the full-sized icon, which means much detail is lost. While this method of representation will persist for — 
compatibility, we will provide an additional one. 

An application will specify a smail icon to MultiFinder in a manner parallel to the method currently 
used for specifying the application's full-sized icon, via a series of resources. 

To implement a smail icon for MultiFinder 's use, an application should install the following 
resources: 


1) An SICN resource with a unique resource ID. The icon dimension is 16 by 16 bits. The icon 
mask is ignored. 

2) ABNDL resource with an entry of type 'ICN#’. Store the icon resource ID in the ‘rsrc!D’, and set 
a‘locallD’. Note that this resource and entry will already exist if you have specified a full-sized 
application icon for the Finder. 

3) An FREF resource of File Type matching your application file type (generally, ‘APPL’ ). Store 
the 'BNDL’ resource ‘locallD' in the ‘localiconiD’. This resource, too, will already exist if you 
currently have a full-sized icon for the Finder. 


This is consistent with the.small.ican.support proposal. from. Finder in. Big Bano. 


« Add/Remove Items from MultiFinder Portion of Apple Menu 

Applications will be able to add or rémdve items inthe portion of the Apple Menu that is under 
MileCindare control. Currently, trie Apple-Meny portion that.lists the active‘applications can only be 
adjusted by MultiFinder. =§ ** Na ff 

This change will enable the.Firides.to insert menu items that cquid be used as shortcuts to specify 
objects so open (e.g. folders,:docdments, applications, DAs, and panels). * 


Details to be determitied as. user interface issues are resolwed. 


¢« Debugger Support. Mea lat rs i i 

MultiFinder 7.0 provides, support for the-new high-level debugger, SADE. Currently, no such 
support exi sts. eR ese a sane negnesee nee AARP ARRRE, ex STD nee 

SADE is high-level in the sense that it is an application and is not exclusive of other system 
activity, in contrast to system-level debuggers such as MacsBug and TMON. Part of the support consists 
of the ability to manipulate the trap, memory, and register contexts of other applications. Absolutely no 
interlocking with the activity of the victim is made by these routines. This is the burden of the debugger 
designer. The other part of the support is the ability to “register” a process as the high-level debugger on 
the system. This process then has first right of refusal for handling system errors and hardware 
exceptions. Should it choose to handle an error, the process then is switched into and may execute like 
any other application. The only application that does not continue to execute is the one that was running 
when the error occurred. 


IMPORTANT: This interface is known only by SADE. Conceivably, it could made public at some 
future date. 


Constants 


Following are the error codes from the new debugger interface routines. Errors that “bubble 
up” from traps called within these routines may be returned as well (for example, if 
MF RegisterDebugger is unable to locate its support resources). 


CONST 
unknownCall = ~600; 
procNotFound = -601; 
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Routines 


FUNCTION MFGetTrapAddress (procID: ProcessID; VAR trapAddr: Ptr; 
trapType: TrapType; trapNum: INTEGER) : OSErr; 


MFGetTrapAddress sets trapAddr to the trap address that the specified process is using for the 
trap described by trapType and trapNum. This will be the user-defined address, if any, or the 
current one. If an error occurs, trapAddr is not changed, and a negative error code is returned. 
Result codes: no€Err No error 

paramErr prociD not within defined range 
procNotFound No process with specified prociD 


FUNCTION MFRecordTrapAddress (procID: ProcessID; trapAddr: Ptr; 
trapType: TrapType; trapNum: INTEGER) ;: OSErr; 


MFRecordTrapAddress patches the specified process’ address for the trap described by 
trapType and trapNum. It is the interprocess equivalent of NSetTrapAddress. The previous 
patch value is lost (use MFGetTrapAddress before this cail if you want to restore the patch later). 


If an error occurs, the trapAddr is is not.recorded, and a negative error code) is returned. 
Result codes: so€rr~ ~No error - 

paramEr proc{D not within defined range 

procNotFound No process | with Specified. prociD 


FUNCTION MFRoadWriteMéii” “(peqcID: prodessID; précherPtr: Ptr; 
byteCount : LONGINT; callerMemPt 5% Ptr: 
readorWrite: BOOLEAN) : OSErEry 


MFReadWriteMem. moves a block of byteCount conseciitive bytes from the specified process 
to the caller, or vice versa. No pointers are/updated. If, the readOrWrite flag is True, the bytes 
are moved from the process to the caller (ie. a “read” Occurs). . ‘If the flag is False, the bytes are 
moved from the caller to the process (i. aa “write” octurs). This i is an interprocess BlockMove. 
if an error occurs, ‘he.bytes are moved, “and a negative error code is returned. 
Result codes: nor“ No error 

paramErr prociD not within defined range 

procNotFound No process with specified prociD 


FUNCTION MFReadWriteFPURegs (procID: ProcessID; callerMemPtr: Ptr; 
readOrWrite: BOOLEAN) : OSErr; 


MFReadWriteFPURegs gets or sets the floating point unit (FPU) user register context for the 
specified process. The registers are ordered fp0-fp7, fpcr, fpsr, fpiar. They are returned zero if 
the most recent FPU context save did not require the register values. Furthermore, this 
condition causes the fper, fpsr, and fpiar to be zeroed when the context is restored. See the 
appropriate Motorola FPU manuals. If an error occurs, no registers are copied, and a negative 
error code is returned. 

Result codes: noErr No error 
paramErr prociD not within defined range 
procNotFound No FPU in machine, or no process with specified prociD 


FUNCTION MFRegisterDebugger (procID: ProcessID; entryRoutine: procPtr; 
exitRoutine: procPtr; toAppRoutine: procPtr; 
debugKey: CHAR) : OSErr; 


MFRegisterDebugger informs MultiFinder that the specified process is to be the registered 
debugger. 
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The prociD is the process descriptor of the debugger-to-be. If it is 0, the current debugger is 
deregistered and any hung processes it was debugging are terminated with MFKill. If it is non- 
zero, the specified process becomes the registered debugger, superceding any current 
registration without terminating any processes. 


The entryRoutine is what MultiFinder calls when a system error or hardware exception occurs. 
The registers are unchanged from when the condition occurred. The low memory global 
DSErrCode ($AF0) contains the error code. The stack contains the retum address (Ptr), the 
current process descriptor (LONGINT), and a pointer to a BOOLEAN. These are followed by an 
exception frame if DSErrCode is a hardware exception. The BOOLEAN being pointed to is a 
flag that the debugger should set before it returns to MultiFinder. The stack for the 
entryRoutine may be represented pictorially: 
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Figure 1. Stack frame for registered debugger entryRoutine 


The entryRoutine's sole purpose is to decide whether the registered debugger should handle 
the error, set the pointed-to BOOLEAN flag appropriately, and return. If the flag is zero, the 
system debugger, if any, is entered. If the flag is non-zero, the registered debugger will be fully 
switched in so it can do the real work. 


The exitRoutine is called to clean up and resume the machine after the debugger returns from 
its work and is switched out. Its stack has a retum address (Ptr) and the current process 
descriptor (LONG). If the exitRoutine retums rather than resuming the machine, the system 
debugger, if any, is entered. 


The toAppRoutine is called just before the event calls return an event, indicating that control is 
about to return to the application. The debugger should perform any necessary work such as 
reinserting breakpoints. It gets no parameters; its stack contains only the return address (Ptr). 
This routine is not called if the toAppRoutine procPtr is Nil. 
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The debugKey is a key that the user can type together with the command and option keys to 
enter the debugger asynchronously. The debugger receives a system error 69 (decimal) when 


this occurs. 
if an error occurs, MFRegisterDebugger does not register the debugger, and a negative error 
code is returned. 
Result codes: noErr No error 
paramErr prociD not within defined range 
ResEr (bubbled-up resource manager error ) 


Programmatic Changes 


¢ DAs Launched In Their Own Layer 

Each desk accessory will be launched in its own layer. Currently, DAs are launched in a common 
layer (that of the "DA Handler* system application). 

This will allow DAs and applications to operate in a much more similar manner, leading up to the 
day when DAs are completely superceded by small applications. The implementation will support the 
existing DA programming model, and does not require that new DAs be written differently. 


- Enhanced Application Launch Control nny 

MultiFinder 7.0 will allow additional progratnmer control of application launches. Currently, 
MultiFinder extends the Segment Manager Launch trap parameters to let the programmer specify 
characteristics such as non-selfdestructive-taunching and multiaunching:“The new scheme entends the 
parameters even further, £ fawn, sad , io 4 

Specification of the application code resource file for Launch has“always been by file name with 
the current directory assumed. Thisis‘cumbersorie and not consistent with the specification mechanism 
used in the File Manager. The first addition, therefore, includes a volume reference number (or directory 
ID), and a working directory reférence number to completely specify the file. Note that using Zero in both 
fields provides functionality. équivalent to the current trap. f ; 


Speciality applications may have size requirements inadéquately represented by the algorithm 
Launch normally uses to sat the process.overall size and stack size. Th@ second addition to launch 
control, therefore, is the option to override this algérithm for eitHier or both sizes. For each, a new bit in the 
launchFlags indicates whether the-caller.is-ovérriding. If the flag-is-False, Launch uses the normal 


algorithm. If the flag is True, a ong word value elsewhere in the parameter block is used directly. 


Constants 


Following is a new error code from the LaunchApplication routine. Errors that “pubble up” from 
traps called within this routine may be returned as well. 


° 


CONST 
memF ragErr = -602; 
Data Type 
Following is the type definition of a process descriptor returned by LaunchApplication. 
TYPE 
ProcessID = INTEGER; {process descriptor} 


cepa AGRE SS A eS RL LL eee 
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Routine 
Launching an application. This is the high-level interface to the Launch trap. 


FUNCTION LaunchApplication (name: StringPtr; vRefNum: INTEGER; 
dirID: LONGINT; soundBuffers, fileFlags: INTEGER; 
returnLaunch, setSize, setStack: BOOLEAN; 
processSize, stackSize: LONGINT; 

VAR procID: ProcessID) : OSErr; 


Result codes: memFullErr No room to launch application 
memFragErr No room to launch application having special requirements 
resNotFound Can't find CODE resource 0 for application 
paramErr Specified partition size too small for this application 
ResErr (bubbled-up resource manager error ) 


Proper identification of the parameter block is simple, yet crucial. It consists of specifying the 

block length (bytes) in the extendedBlockLen field. If a field is omitted by dint of this length, its 
value is unspecified. :Specifying-a-vRetNuni, but no-dirlD;-is equivalent-to-specifying a dirlD of 0. 
Leaving the leone or stackSize ye mois causes Launch to ciaaie the normal value 


srevverrerelerrvererreeere Merete ees 


Consiants 
; New error code far Launch 
memF ragErr etal “EQU 602 
; New flag bits in thie laufichFlags used by Launch : 
overrideStackSize i -EQU #11 f #flag to overtide stack size 


overrideProcSize ~~EQU 12 fe ;flag to override process size 


Structure of newest Launeli Paramiéter Block 


name Name of code resource file (long) 
soundBuffers Sound buffers (word) 
launchBlockID Specifies whether block is extended (word) 
extendedBlockLen Length (bytes) of parameter block (long) 
fileFlags fdFlags from application file information (word) 
launchFlags Launch control flags (word) 
vRefNum vRefNum/wdRefNum for application file (word) 
dirID Directory ID for application file (long) 
processSize Process size override (long) 
stackSize Stack size override (long) 

Trap Macro On Entry On Exit 
_Launch AO: parameter block pointer AO: parameter block pointer 


DO: error code or processiD (word) 


¢ More Access To Other Applications 

Applications will be granted greater access to active applications, including their own. Currently, 
there are few clues for a process that other applications are executing, and no methods for process 
control. This is inconsistent with the process management facilities found in many multi-tasking 
environments. 

MultiFinder 7.0 will provide a number of basic routines, with associated data structures and field 
definitions, to correct this. In addition, a new event will inform a process of the termination of any 
application it has launched. They are outlined below. Note that most require a process descriptor as an 
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input parameter to uniquely specify process. The caller should not randomly generate this value, because 
many are illegitimate. Instead, use the values returned by various existing traps such as Launch, 
MFGetPID, or the “all” variation of MFGetProcinfo. 

The existence of process management calls will be determined from the SysEnvirons record. 


Resources 


The SIZE resource has a new flag defined. It specifies whether the application wishes to receive 
Notification upon termination of one of the applications it launched. 


boolean ignoreAppDiedEvents [* no, do not receive notification */ 
acceptAppDiedEvents I" yes, receive notification */ 


Constants 


Following are new error codes from the new process management routines. Errors that “bubble 
up” from traps called within these routines may be returned as well. 


CONST 
unknownCa>? = -600; {trap or selector not defined} 
PLOCNOCFOMNG. cnn OOTTE —pacummmmemnnenndy 
memF ragErr = -602; : : 


: 
? > 


Following are the values.for-the State field of the Progessinfe’ RECORD retiimed by 
MFGetProcinfo. The field represents the current.execution state of the.process. 


te, 
, 


CONST tent, , , a i 
piStateReady” = ty {r@ady to be s¢heduled to a CPU} 
piStateNull” = 2) {disqualified from CPU scheduling} 
piStateBaékRun = 3;: {executing if the background} 
piStateRun ; = 43 {frontmost user process} 
piStateUpdate’, =.5; {gurrent, but only for an update} 
piStateDébug = 6; {moving from READY to RUN as debugger} 
piStateMoviltg.......8.7¢°" {moving from“READY to RUN in foreground} 
piStatePuppet = 8; {getting scratchpad events} 
piStateSleeping = 9; {temporarily disqualified from CPU use} 


Following are bit settings for the taskMode field of the Processinfo RECORD returned by 
MFGetProcinto. The field is a copy of the task mode parameter (LONGINT) originally passed to 
Launch to launch the application. The low order word will generally be a copy of the flags field 
from the application file's SIZE resource. The high order word is 0 except for a copy of the 
*multi-launch” flag from the launchFlags passed to Launch (which, in turn, is a copy of the 
“shareable” flag from the application file information). 


CONST 
piModeMultiLaunch 


65536; {process may be one of ...} 
{many for same application} 


piModeGet SuspResEvents 16384; {same as in SIZE flag} 


piModeGetBackTime = 4096; {same as in SIZE flag} 
piModeActivateOnResume = 2048; {same as in SIZE flag} 
piModeOnlyBackground = 1024; {same as in SIZE flag} 
piModeGetFrontClicks = 512; {same as in SIZE flag} 
piModeGetAppDiedEvents = 256; {same as in SIZE flag} 
Data Types 
Following is the type definition of a process descriptor, and a prototype of the record returned 
by MFGetProcinfo. 
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canna fren SS a SS 


TYPE 

ProcessID = INTEGER; {process descriptor} 

Processinfo = RECORD 
State: INTEGER; {see piStatexx constants above} 
ProcID: ProcessID; {process descriptor} 
Type: ' OSType; {application file type} 
Signature: OSType; {application file signature} 
reservedl: LONGINT; {reserved} 
reserved2: LONGINT; {reserved} 
Taskmode: LONGINT; {see piModexx constants above} 
SuspendResume: BOOLEAN; {taskmode has acceptSuspendResumeEvents} 
Background: BOOLEAN; {taskmode has canBackground} 
MFAware: BOOLEAN; {taskmode has multiFinderAware} 
Launcher: ProcessID; {launcher ProcessID, or 0} 
ProcessSize: LONGINT; {total application size} 
StackSize: LONGINT; {application stack size} 
Slices: LONGINT; {count of times process has used CPU} 
FreemMem: LONGINT; {free memory in application heap} 
Name: Str31; {application name (inline) } 
vRefNum: _—s_—s vRefNum#""y {application file vRefNum/WDRefNum} 
SAD: oa /  acaauadeaieaa: 


Following are new: ‘routines ‘available in MultiFinder 7.0. ae 16 errge cos constants above for 
the numerical equivalents Of the return codes. F 


FUNCTION MEcetPib : ProcessiD; . / 

MF GetPid returis the caller's process destriptor. Thefe are no 6 poss errors. 

PROCEDURE MESheep (EXékcoung x “LONGINT) 2 z 

MFSleep causes the callers. process to be ineligible for execution until tickCount event calls 
have been made, or until another process calls MF Wakeup against it. Use of the CPU is turned 
over to the next eligible process or driver, if any. It is not allowed if the caller is being switched in 
or out. If an error occurs, MFSleep returns and the process is still eligible for execution. 


FUNCTION MFGetProcInfo (procID: ProcessID; 
VAR dataRec: ProcessInfo) : OSErr; 


MFGetProcinfo fills the dataRec with information regarding the process specified by prociD. 
See the definition of Processinfo RECORD above. If an error occurs, MFGetProcinfo returns 


without altering the dataRec. 
N.B. This routine will be altered to allow prociD to mean "self" or “all processes”. 
Result codes: no€Err No error 

paramErr prociD not within defined range 


procNotFound No process with specified prociD 
FUNCTION MFKill (procID: ProcessID) : OSErr; 

MFKill removes the specified process from the system. The application is forced to terminate 
with no chance to recover or perform any cleanup. The exit status is 0. The application that 
launched the terminated process will receive an ApplicationDied event wan a copy of the exit 
status. 


If an error occurs, MFKill returns an error code and the process is not removed. 
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Result codes: noErr No error 
paramErr prociD not within defined range 
procNotFound No process with specified prociD 


FUNCTION MFWakeUp (procID: ProcessID) : OSErr; 


MFWakeUp revives the specified process from its “sleep” caused by a call to MFSieep. If an 
error occurs, MFWakeUp returns an error code and revives no process. 


Result codes: no€Err No error 
paramErr prociD not within defined range 
procNotFound No sleeping process with specified prociD 
Event 
Sub-application terminati 


Under MultiFinder 7.0, an application can elect to receive a special event record upon 
termination of any application it has launched. To sign up, an application must have the 
acceptAppDied flag set in its own SIZE resource before it is launched. The event record format 
is defined below. 


The what field will identity the everd a as an appt “This i is a ‘general event type that 
encompasses several process situations, such as suspend and resume. A selector in the high 
order byte of the message field-must:be examined fa ‘further identity the’ ‘event. 

The message field: a LONGINT) will ‘Be: divided into three parts: "For £=plicationDied the selector 
will be 253 decimal ($FD_ hexadecimal). The second byte is réserved and 0. The low order word 
will be the exit status. The exit status is thé. value of DSEmCode when the application called 
ExitToShell, or 0 it the termination: was forced. F 

The where field “il contain the process descriptor. 
The when and moditier fields will be 0,.. 


The message field of the event record may be ‘estecemad picioiibiy: 
31 24 23 16 15 | 0 


reserved exit status 


Figure 2. Message field of the ApplicationDied event record 


* Mostly Transparent Temporary Memory 

MuttiFinder 7.0 will expand and simplify application access to temporary memory. Currently, 
MultiFinder parallels a subset of the memory manager calls in a "temporary memory” scheme, providing a 
pro tem solution for memory requests that can not be satisfied from the application or system heaps. It is 
understood that the memory must be in use for extremely short periods, and should be freed before the 
next event call. Memory allocated under the temporary scheme must be manipulated by specialized calls 
within the scheme, rather than by the general memory manager calls. 

Some software writers object that the scheme requires that they track their memory closely 
enough to determine which set of calls is appropriate for a given handle, which uses excessive time and 
space. 

The programmers’ model under MultiFinder 7.0 is that the source of temporary memory remains 
unknown, but that, once allocated, temporary memory now can be manipulated just like memory from the 
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application or system heaps. Therefore, temporary memory allocation and other heap operations are 
specialized, but operations on existing temporary blocks are made from the general memory manager. 
The life of the memory should be as short as possible, but will definitely end when the application 
terminates (see Automatic Tracking of Temporary Memory, below). 


The specialized subset of calls implemented in MultiFinder 6.0.x temporary memory scheme is: 
1) MFTopMem 
2) MFFreeMem 
3) MFMaxMem 
4) MFTempNewHandle 
5) MF TempDisposeHandle 
_ 6) MF TempHLock 
7) MFTempHUniock 


The additional specialized call implemented in MultiFinder 7.0 is: 
FUNCTION MFTempNewPtr (logicalSize: Size) : Handle; 


MFTempNewPtr attempts to allocate a new nonrelocatable block of logicalSize bytes for 
temporary usage and retum a pointer tg, it. jt an error occurs pie Mualawaii will return Nil, and 
ResErr will contain the.error.code..... x ictes 
Result codes: naErr No errer iP 

memFullErr _ Not enough rom sel ata 


In MultiFinder 7.0, these general remarry managet.calls will work evén if tHe handle or pointer — 
being passed was allocated by one‘of the temporary memory ruuivies. Nove that this obsolete s 
MFTempDisposeHandle, MP Tomer hors: x Subteneriaoct oy will rephain, for compatibility). 


1) DisposHandie. 4 11) HUnLock 

2) EmptyHandie ™. : 12) HPurge 

3) GetHandjeSize : #18) HNoPurge ; 

4) SetHandieSize % = 14) HSetRBit id 

5) RecoverHandle _45) HCirRBit 

6) ReallocHandlé ~~" 16) HGetState* 
7) DisposPtr 17) HSetState 

8) GetPtrSize 

9) SetPtrSize 

10) HLock 


important: Although you can determine the zone from which the temporary memory is 
generated, DO NOT use this information to make new blocks on your own. Doing so would be extremely 
hazardous! 


Note that some of these calls rely on the current zone if the handle has been purged. They have 
been made to work correctly in this case even though the current zone is the application or system zone 
and the handie is from a temporary block. 


The existence of transparent temporary memory will be determined from the SysEnvirons record. 


° Automatic Tracking of Temporary Memory 

MultiFinder 7.0 will automatically free any outstanding temporary memory blocks when the 
application that allocated them terminates. Currently, applications are left to their own good graces, but 
this is bad policy because the memory blocks come from a critical area and must be recycled. 

Because memory is tracked per application, this restricts its use to applications, or at least to code 
running on an application's behalf. In particular, drivers can not make temporary memory calls at accRun 
time if they plan to keep the memory across event calls. 


Apple Computer Inc. page -11- Company Confidential 


MultiFinder 7.0 ERS (first draft) | . April 11, 1989 


This may break a few applications that expect the memory to remain longer. However, itis a 
necessary step that does not violate the basic assumption that the usage is to be truly temporary. 
Developers were notified in the Programmers’ Guide to MultiFinder that the memory is to be disposed as 
soon as possible, "before the next event call”. 

The existence of temporary memory tracking will be determined from the SysEnvirons record. 


Wish List (time permitting) 
¢ Integrate Layer Handling Into Layer Manager (aka Glass Plus) 
MultiFinder 7.0 will remove all of the layer manager patches that MultiFinder uses. Currently, ail 
control of how windows are activated/deactivated during process switching is within MultiFinder. This 
would be a significant cleanup to MultiFinder. 
Because this fixes no bugs, and provides no new functionality for MultiFinder, it will be 
undertaken only if all mandatory ERS items have been completed. 


¢ Integrate Menu Handling Into Menu Manager 

MultiFinder 7.0 will remove all of the menu manager patches that MultiFinder uses for control of 
the Apple menu. In the past, it has been necessary for MultiFinder to patch the MDefProc to obtain 
sufficient functionality to maintain the Apple menu. The menu manager has since been upgraded, and it 
now makes sense go back to it. 

Because this fixes no bugs, and provides no new functionality for MultiFinder, it will be 
undertaken only if all mandatory. ERS. items.have been completed... enncnnnncnnny 
- Desk Accessory Launch ee ae ee 

MultiFinder 7.0 will providé’a triéaris to Talinch a desk aécessory directly. Gurrently, the only way is 
to call OpenDeskAce, which limits controt-ef the launch. Ip-patticular, it means that desk au_27sores must 
be located inthe system file; *“ es ff 

Because of time constraints this feature will be undertaken only if all mandatory ERS items have 
been completed. al % 5 rs Ps 


¢ Puppet Strings %, i i f i 

MultiFinder 7.0 will augment the puppet string mechanism with message passing under the new 
IPC facility. Currently, “puppet strings*.(a’Series of.clever responses to the event calls) tease an. 
application into correct layer Switching and other-ifter-application operations. It is rather awkward and 
inefficient, but is compatible with applicatiotis that only know the single application environment. 

Because applications currently manage to work with puppet strings, and because of the lack of 
development in this area, this project will be undertaken only if all mandatory ERS items have been 
completed. 


eee rte CES UD RE SAE SN a a 
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INTRODUCTION 


This document describes a collection of MacOS enhancements which permit the defini- 
tion and use of multiple foreign file systems on a single Macintosh. These enhancements 
provide a systematic way to integrate and control the use of foreign file systems and ex- 
pand the potential of foreign file systems in the future. 


These enhancements are: 
The File System Manager (FSM) 
An HFS Foreign File System Interface,(The HFS Component Interface, or HFS Cl) 
An Enhanced Disk Initialization Package (PACK2). 


The File System Manager maintains information about installed foreign file systems and 
provides a general framework for granting those file systems access to Macintosh OS or 
Toolbox components. FSM is described in Section 1. 
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Section 1. 


File System Manager 


This section describes a new MacOS facility known as the File System Manager (FSM). 


Overview 


FSM is a new MacOS facility which manages the use of foreign file systems. FSM 
provides a general means by which foreign file systems can be installed, identified, and 
interfaced to the MacOS. 


Installation of foreign file systems will usually be accomplished by an INIT at startup time. 
The INIT 31 mechanism describegvitrfnside Macintosh, vol. IV, ch 29 will be used to load 
and execute a foreign file system install progedure. me install pre cedure will make an 


system. A detailed'escription of faé FSD is givén below under "FSM Data Structures". 


Four service calls are provided by FSM to maintain and access information in the FSD. 
They are defined as follows: 


InstallFS Adds a new file system definition to the system. A new 
FSD is created. 


RemoveFS Removes a foreign file system definition from the system. The 
FSD for the specified foreign file system is deleted. 


GetFSInfo Returns the FSD information about an foreign file system. 

SetFSinfo Sets the FSD information about a foreign file system. | 
A programmatic description of the each of these calls is given below under "FSM Calls". 
FSM also provides a general framework for interfacing with foreign file systems to a previ- 


ously defined and exported Mac OS or Toolbox component. This framework includes the 
FSD Queue which identifies known foreign file systems and provides storage for interface 
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parameters. 


Concurrently with the development of FSM, a new interface mechanism known as a 
component interface has been defined. A component interface can be any functional 
interface exported by a given Macintosh OS or toolbox component, much like our current 
HFS external file system interface. Each component interface is an independent 
interface, defined and managed by the particular MacOS or toolbox component. This 
includes the definition of the calls involved, the dispatching of calls to the foreign file 
systems, and the execution environment in which those calls operate. 


The connection between a given component and a foreign file system is defined by the 
interface parameters contained in the FSD. A minimum set of parameters includes a flag 
byte and a a pointer to a code resource. The flag byte enables or disables the component 
interface and represents the busy state of the interface. The pointer represents a code 
resource in the foreign file system which is responsible for processing redirected MacOS 
calls. Which MacOS calls are redirected js-nart of the Component Interface definition. 
Other component interfaq a Dpare Dorjent interface. 


Initially, two component jiterfaces are being d¢fined for er FSM, anew HFS 
Component Interface rep externaf file sygtem interface (see Section 
2), and anew Disk Initiakzation dmponent | terfac enabling initialization of 
foreign file system volumes 0 Osh (see Sectid 


Both the FSD and component interface mechanism are designed such that new 
component interfaces can be added at a later time. 
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FSM Data Structures 
Fil Descriptor 


FSM maintains a File System Descriptor (FSD) for each installed foreign file system. 
Included in an FSD is the name and id of the foreign file system, file system context 
parameters, and some interface parameters for each OS and Toolbox interface used by 
that foreign file system. 


An FSD is created by the InstallFS File System Manager call. Information in the FSD is 
subsequently made available via a GetFSInfo call to the File System Manager. 
Information in the FSD is can be updated using a SetFSiInfo call. An FSD is removed by 
the RemoveFS call. 


The FSDRec and supporting GetFSInfo and SetFSInfo calls are organized such that the 
FSDRec can be extended at a latertime. Future versions of the FSM will support more 
MacOS Compone 


The structure of anj/FSp-is-as 
ComponentEnable 


Component Busy 
FSDShutdown 


{This number of bytes must be even} 
END; 


FSDRec = RECORD 


FsdLength : Integer; {length of an FSD} 
FsdVersion : Integer; {version number} 
FsdFSID : Integer; {a unique file system ID as defined in HFS} 
FsdName “S)SE2315 {file system name string} 
FsdGlobPtr : Ptr; {Pointer to file system global area} 
{ 1 or more optional CompAdapter records } 
END; 


FsdLength is the length in bytes of the FSDRec. 
FsdVersion is the lowest FSM version number the foreign file system can support. 
FsdFSID is a binary WORD signature which uniquely identifies the foreign file system. 


This is the same FSID (File System Identifier) used by HFS to identify foreign file 
systems. An FSID equal to zero designates Apple file systems (MFS and HFS), and is 
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reserved. FSID values from 1 to 255 are reserved for foreign file systems that determine 
their FSID’s dynamically, i.e., by searching the drive queue. FSID values above 255 
should be registered with Macintosh Technical Support. This value is checked by 
InstallFS to insure that the FSID for a foreign file system which is already present in the 
system is not duplicated. The FSID is passed as a parameter for all calls. 


FsdName is a Pascal name string which is also used to identify the foreign file system, 
although it is not guaranteed to be unique. This parameter is used by the Disk 
Initialization Package (PACK 2). The name is displayed in a dialogue box that presents 
the user a choice of file system formats with which a disk may be initialized. 


The pointer to an optional foreign file system global area is kept in FsdGi/obPtr. It is 
passed as a parameter for all calls. NULL indicates that no global area is allocated. This 
global area is allocated by the foreign file system install code. 


This following portion of the FSDRec j is composed a 1 or more Component Adapter 
records. To support the 
for the HFS Cl. If a forei 


system that FSM is an orphan. See RemoveFS for use of FSDShutDown. 
The meanings of the low-order three bytes of CompintrfMask are interface dependent. 


All MacOS calls involved with the Component Interface calls are dispatched to common 
code pointed to by CompintrfProc. 


The number of offsets after Comp/ntrfProc is determined by the Component Interface. 


Sections 2 and 3 of this ERS specify Component interfaces for the HFS Cl and the Disk 
Init Interface. 


FSD FSD 


The FSDs for installed file systems are maintained in a queue known as the FSD Queue 
(FSDQ). A pointer to the head of the queue is kept in a data structure known as FSMVars 
(See "FSM Variables" below). FSDQ is a standard MacOS queue of type $81. The 
queue is ordered in installation sequence. 
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FSM Variabl 


FSM Variables (FSMVars) is an new internal data structure maintained by the File 
System Manager. It serves as the root of the FSM data structure hierarchy. A new low 
memory variable (at location $BB8) will be used to point to FSMVars. For now, FSMVars 
will contain a pointer to the MacOS Queue Header for the File System Descriptor Queue 
(FSDQ). 


The general structure of FSMVars in figure 1-1 


$BB8 


FSMVarsPtr 


Figure 1-1. FSM Variables (FSMVars) 


Note: the pointer to the global area associated with each foreign file system is kept in the 
FSD. 
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FSM Calls 


The services provided directly by FSM include the installation and removal of foreign file 
systems and the maintenance of information about those file systems. These services 
will be implemented as four new calls: InstallFS, GetFSinfo, SetFSinfo and RemoveFS. 
Each call is described separately below. 


All of the FSM calls are stack based and execute synchronously. InstallIFS and 
RemoveFS call the Memory Manager and thus cannot be used from interrupt level. 
GetFSinfo and SetFSInfo are executed immediately with no intervening memory 
management activities, and thus, may be executed at any time. 


Note, the FSM calls are not HFS calls, thus they are not controlled by the HFS queuing 
mechanism. 


for that file system is crpate 
to aFSDRec. It’s contents gre 


and the fixed length FSDRec header 
¢ CompinirfLen is not even 
* CompintrfTag is invalid 


While the InstallFS call will be normally done by INIT code at system startup time, to 
facilitate automatic installation of foreign file systems, this call may be made by any 
application. 


Note: InstallFS initializes all CompintrfMask high order bytes to zero. This means that 
the foreign file system will not receive calls and that the interface is not busy (i.e. FSM 
will accept SetFSInfo calls.) A SetFSInfo call must be used to enable the component 
interface. 


Function RemoveFS(FSID : integer) : OSErr; 
RemoveFS removes a file system definition from the system. This call removes the 
FSD identified by FS/D from the FSD Queue and deallocates the FSD memory. If 


FSID does not exist in FSDQ, an error is returned. If ComponetBusy for any 
Component Adapter is set, FSM sets FSDShutDown and and resets ComponetEnable, 
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then returns an OSErr to the caller. The foreign file system may get the chance to poll 
FSDShutDown and take appropriate action. The MacOS Component Interface knows 
that the foreign file system is busy and has been informed of RemoveFS. 


Function GetFSInfo(FSID:integer; index:integer; VAR fsd:FSDRec; 
size:integer; VAR actualSize:integer) :OSErr; 


GetFSInfo returns the FSD information about a file system. If Index is zero, GetFSInfo 
returns the FSD information about the file system specified by FS/D. If Index is non- 
zero, GetFSInfo returns the FSD information about the n-th FSD where n is the 
contents of Index. An error result is returned if the value of Index is too large. 


size and FSDRec contain the size and location of the buffer in which to place the FSD 
info. The actual size of the information is returned in actualSize. 


The format of the buffer is the same as an FSD. The content of the target FSD is copied 
into the buffer. The amount copie 
specified in size. 


FSDRec contain the sige and/ocation/of the buffer con aining the new FSD info. 

The format of the bufferisthe-sdime as an FSD: arget FSD is modified based on 
the contents of the buffer. FsdLength, FsdFSID, and FsdVersion cannot be modified by 
this call. Also, the interface parameters for a component interface cannot be modified if 
CompinterfMask has CompBusy set to 1. SetFSInfo returns an error to the caller. 


January 13, 1989 Page-8- 


File System Manager Apple Confidential 


Component Interfaces 


An FSM component interface is a functional interface exported by a given Macintosh OS 
or toolbox component to foreign file systems. Each component interface is an 
independent interface, defined and managed by the corresponding MacOS or toolbox 
component. This includes the definition of the calls involved, the dispatching of calls to 
the foreign file systems, and the execution environment in which those calls operate. 


FSM is not involved with the definition or operation of component interfaces, it simply 
provides a general framework within which foreign file system can access these interfac- 
es. This framework consist of a set of interface parameters plus some conventions for 
dispatching calls to foreign file systems. 


Component Interface Parameters 


Access to a componentiinterface is definep by a Bet of interface param gters maintained 


As shown in Figure 1-4 sist of two :An FSM byte containing 
flags pertaining to FS ree byfes of flags pertafning to the component 
interface. i 

3130 24 23 0 


FSM byte Interface dependent flags 


Figure 1-2 Component Interface Dispatch Mask 


Three flags are defined in the FSM byte, they are: 


bit 31. enables / disables the use of this interface. Once enabled, the MacOS 
component may begin dispatching calls to the foreign file system. The foreign 
file system should set this bit (via SetFSInfo) once it is ready to receive calls. 


bit 30 if set, designates that the interface is "in use" or “busy”, i.e., one or more Calls 


are outstanding. This bit is maintained by t the MacOS component and used by 


FSM to control the use of SetFSiInfo. 
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bit29 if set, designates that the FSM has processed a RemoveFS for this foreign file 
system. 


The bit definitions for the last three bytes of the dispatch mask are defined by each 
individual component interface. For the new HFS interface the dispatch mask is known 
as FsdHFSMask. For the new Disk Initialization interface the dispatch mask is known 
as FsdDI/Mask. 


Additional interface parameters other than the dispatch mask and code pointer may be 
included in the FSD for a given component interface. These are component interface 
dependent parameters and are not required by FSM. 


Di hin nvention 


In order to insure some baie sl of uniformity across Soil ae interfaces, FSM 
imposes some co oy-CemDE Swe 


1) The File Syste 
the foreign file 
information in q 


3) The component should set the "busy" flag (bit 30) in it's dispatch mask when the 


interface is busy. This will prohibit modification of it's interface parameters by a 
SetFSInfo call. 
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Section 2. 


HFS Component Interface 


Overview 


The HFS Component Interface is a new version of the existing HFS external file system 
Interface which operates as an FSM component interface. In addition to the benefits 
resulting from being a component interface, the new interface also includes a number of 
other significant enhancements. Those enhancements are: 


1) 


o 
~—e” 


The interface has been cleaned up. Wg foreign file system no longer needs to be 
concerned with call dependent regigte ements: Or pass calls along to fellow 

foreign file systems. 
foreign file system v 
the current register 


Database Calls. 


The new interface maintains context variables for each foreign file system. This 
includes the pointer to an foreign file system global area (FsdG/lobPtn plus an 
alternate stack context supporting caching and asynchronous IO. 


A new HFS utility call known as HFSUtil has been added. The call provides a set 
of utility functions for use by foreign file systems. These utility functions are used to 
access the HFS internal data structures, and to assist in the processing of the IO 
parameter block. A detailed description of HFSUtil is given below under "HFS Utility 
Calls". 


foreign file systems can now utilize the HFS cache and IO facilities. This capability 
is provided by another via a second HFS utility trap known as CachelO. A detailed 
description of CachelO is given below under "Cache IO Calls". 


The HFS Component Interface will maintain the existing HFS execution environment for 
it's calls i.e., the file system queuing via FSQueue and CmdDone, synchronous and 
asynchronous IO, and interrupt levei restrictions. 
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Interface Parameters 


The FSD interface parameters for the HFS Component Interface are shown below. 


HFSCITagID = $Ol 

HFSCILen = $19 

ComponentEnable = $80000000; {Component interface is enabled} 
ComponentBusy = $40000000; {Component interface is in use} 
FSDShutdown = $20000000; {Component interface is orphaned} 
doesHFS = $00800000; {File system supports HFS calls 
doesAShare = $00400000; {File system supports AppleShare 

Shared Environment calls} 

doesASDTop = $00000400; {File system supports AppleShare 


Desktop Database calls} 


CompAdapter = RECORD 
CompIntrfMask: LongInt; 
CompiIntrfP yee ere 


ispatch mask for Component Interface} 
Pognter : code } 


{Zero or mdre bytes of (parfametey information} 
{This numbd@r of bytes must fbe evdn} 
END; 
; HFS Component] Interface Parameters 
FSQHFS 
FSdHFSL2P ; Ptrfto logical to physical conversion routine 
FSdHFSSTop ; Pointer to ile system stack 
FsdHFSSSize ; e of fil stack 
FSdHFSSPtr iAurrent fife systdm stack pointer 
FSdHFSRsrvl : : ; (reserved fOr Expansion - must be zero) 
FSdHFSRsrv2 : longint ; (reserved for-expansion - must be zero) 


FsdHFS.CompintrfMask is the dispatch mask for HFS Component Interface. It is used 
to manage the operation of the interface. The high order byte of this long word is the 
standard FSM byte. It contains the two flags required by FSM, ComponentEnable and 
ComponentBusy. If ComponentEnable is set, HFS will begin using the interface to 
dispatch calls. ComponentBusy is set each time a call is dispatched to the foreign file 
system and cleared once the call is completed (at CmdDone). 


Three interface dependent flags are defined for the last three bytes of 
FsdHFS.CompintrfMask. These flags refine the subset of the HFS calls that are 
supported by the foreign file system. If doesHFS is set, all of the HFS calls (/nside 
Macintosh, vol. IV, ch. 19) will be dispatched. This includes the original MFS calls, the 
extended MFS calls (those with the HFS bit set), and the HFS specific calls (trap Ax60). 
If doesAShare is set, the AppleShare Shared Environment calls (Inside Macintosh, vol. 
V, ch. 27 ) willbe dispatched. These are the extended Ax60 calls added by 
AppleShare. If doesASDTop is set, the AppleShare Desktop Database calls will be 
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dispatched. These are another set of Ax60 calls added by AppleShare. Note, the 
AppleShare _GetVolParams call is included with the desktop database calls. 


All HFS calls are dispatched to a common code pointed to by FsdHFS.ComplIntrfProc. 


FsdHFSL2P is a pointer to a logical-to-physical translation routine used by the Cache 
IO calls to convert a file relative address to a physical disk address. 


FsdHFSSTop, FsdHFSSSize, and FsdHFSSPtr are optional stack parameters 
supporting an alternate stack used by an foreign file system. The alternate stack is 
used to store foreign file system context across asynchronous IO operations. 


The HFS Component Interface parameters must be initialized (via a SetFSInfo call ) 
when an foreign file system is first installed. 


Call Dispatching 


After determining which volume a file system calljis casas for, i FSID in the volume 


All HFS calls are dispatc de resdurce pointed to by/FsdHFS.CompintrfProc. 

The dispatch mask (Fs4 ComplintrfMask] is used to filter galls destined for an 

foreign file system. If the magk indigates thgt the file oes not support this type 
_Of call, the call is terminated wi "Paramerr" result./ Other wise, the call is passed to 


The FSM foreign file system is called by: 


Procedure FFS(FSID : Integer; FsdGlobal : Ptr; TIOParamBlk : Ptr; 
selectCode : Integer; VolPtr : Ptr); 


A standard stack frame is used to dispatch all calls. It is structured as shown in Figure 
2-1. 
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byte 0 FSID 
(word) 
2 Global Ptr 
(long) 
6 1O ParamBlock Ptr 
(long) 
10 Call Select Code 
(word) 
12 ReqVol 


(long) 


Figure 2-1 .HFS Dispatch Stack Frame 


this parameter wi 


the call. For a_MountVoTcall, this parameter will be zero. 


HFS Utility Calls 


The HFS utility calls are a set of new calls intended for use by foreign file systems. 
These calls provide access to the internal HFS data structures (VCB, FCB, WDCB, etc. 
), and provide a collection of utility functions used to validate and process an HFS call. 


All calls execute "immediately" i.e., are also not queued via FSQueue, and do not 
involve any disk IO activity. Thus, these calls can be used by foreign file systems during 
the processing of other HFS calls. 3 


The HFS utility calls will be implemented using a single trap called HFSUtil.. The call 
will be stack based and use a "call select code" parameter to select a particular call. 


Data Structure Access Calls 
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This collection of calls provide access to the internal HFS data structures. In general 
the new calls provide mechanisms which allocate, release, locate, get information, and 
put information for each data structure. 


Access to the following data structures will be supported: the Volume Control Block 
(VCB) Queue, the File Control Block (FCB) array, Working Directory Control Blocks 
(WDCB's), and the Drive Queue Elements (DQEs). 


The calls are: 


AllocateFCB 
ReleaseFCB 
LocateFCB 
SearchFCB 


AddNewVCB 
RemoveVCB 
LocateVCB 
SearchVCB 
GetVolStatus 
SetUpDef 


SetUpWDCB 
GetWDCBInfo 
CmdDone 


Allocates a free FCB. 

Releases a FCB. 

Locates an FCB given RefNum, VolRefNum/FNum, etc. 
Searches the FCB array, i.e., GetistFCB, GetNxtFCB. 


Removes a VC 
pocales a VEB Hi 


B information (ReaAWDC B). 
Rel rn to galler vig CmdDong Addrdss 


These calls provide a collection of utility functions used to validate and process an HFS 
call. The following calls are included: 


ParsePN 
ChkFRefN 
TstFMod 
ChkVRefN 
TstVMod 


CalFilePos 


Parses an HFS pathname. 

Verifies a file reference number. 

Tests the modification status of a file. 
Verifies a volume reference number. 

Tests the modification status of of a volume. 
Calculates current file position. 


Note: A more complete and detailed description of the HFS Utility Calls will be 
forthcoming at a later revision of this document. 


Cache I/O Calls 
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This collection of calls provides access to the HFS cache and IO routines. These are 
the routines used internally by HFS to perform all reads and writes to/from disk. Using 
the cache IO calls, an foreign file system can utilize the HFS cache memory for storage 
of disk blocks contained on it's volumes. 


These routines may be used in two ways: to read and write individual disk blocks to/from 
the cache, and for reads and writes in-place (directly to/from a user buffer). The in- 
place reads and writes may be any number of contiguous disk blocks. Optionally, up to 
eight blocks of an in-place read or write may be retained in the cache. This option is 
controlled by the calling application using noCache bit in ioPosMode of the IO parameter 
block. 


IO may be performed synchronously or asynchronously depending on the nature of the 
file system call currently being processed. If the file system call is asynchronous, the !O 


is performed asynchronously. If the file system call is synchronous, then the IO is 
performed synchronously. me eel pica context for asynchronous lO i is 


disk address. Ea 


FSD. 


memory buffer for use by the target disk driver. For read operations, the disk driver 
places tag data in the low memory buffer or in a user specified buffer. Note, even’ 
though the Cache IO calls support tags, the disk driver being used may not provide tag 
support. 


Please note: Support for tags may be removed in a future revision of this ERS. 


The Cache IO calls are: 


GetBlock - Gets a specified disk block. 

RelBlock - Releases use of a specified disk block. 
FlushCache~ - Flushes a cache queue to disk. 
MarkBlock - Marks a specified disk block dirty. 
TrashVBlks_~— - Trashes all blocks belonging to a volume. 
TrashBlocks = - Trashes a specified range of file blocks. 
TrashFBlocks - Trashes all blocks of a specified file. 
CacheRdIP_~ - Multiblock read into user-buffer. 
CacheWrlP~ - Multiblock write from user-buffer. 
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MS-DOS 
Foreign File System 


“Spam” 


Karl B. Young 
Jeff Hokit 
Dave Feldman 


Abstract 


pam”) will allow the Macintosh to display 


: disk Aas if they resided-on—a-nagive Macintosh volume. The 
Finder and the sta}dard “Open...” dialog willfdisflay the contests ofa DOS disk in a manner 
familiar to any user of [he“Macinto Applicattons which cap/undgfstand the contents of DOS 
files (e.g., Microsoft Excel seadi 1-2-3 files) can acéess thse files directly without any 


modification to exibtingsOftwarh\ 


The Foreign File System 
B 


for MS-IPOS (a.f.a “S 
files and directories from OS. di 


allaw-~files to be Written toJthe DOS digk from/existing Macintosh applications, 
fear to\have alj the sanfe charactejistics ag native Macintosh files. Icons, 

applications, doc ts, and Aescriptive Aames will all appear on the DOS disk as 
they do on native ¥ When viewéd on a DOS/system, flisks that have visited a Macintosh 
aiesY= pse $-zessiblel the name in the Macintosh world. 

The contents of Macintosh files will be stored in the AppleDouble format. 


About this document 


This ERS is intended for a fairly broad audience, specifically those who are interested in 
what Spam will do, and not how it will do it. It is broken up into three main sections: 1) User 
Interface, 2) Programmatic Interface, and 3) Effects on DOS Disks. 


The purpose of the section on User Interface is to provide anyone familiar with the 
Macintosh an intuitive feel for how a DOS disk would appear to the user and what the user could 
do with such a disk. 


The purpose of the section on programmatic interface is to describe how an application 
would deal with a DOS volume and its files. 


The purpose of the section on the effects on DOS disks is to describe how a DOS user 
would view his disk after it has been on a Macintosh. 


Motivation 

With the SuperDrive (FDHD Floppy) the Macintosh is capable of reading MFM-encoded 
diskettes, the same encoding used by IBM PC’s and compatibles. The Macintosh Il and the 
Macintosh SE also support an external 5.25" drive which can read MFM-encoded diskettes. 
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Right now Apple File Exchange can take advantage of both kinds of drives to transfer files be- 
tween Macintosh and DOS disks. 


As useful as Apple File Exchange is as a utility, it would be even better for the user to be 
able to access files directly from their favorite application. This is especially true for 
applications which can read DOS data directly, that is, without any translation. For instance, 
when a Lotus 1-2-3 file is brought over to a Macintosh without translation, Excel can read that 
imported file directly. 


Spam will provide this desired functionality; it will work in concert with the Foreign File 
System interface of the File System Manager (a.k.a “Shimmer”) to present a DOS disk to all 
applications just as if the disk were native to the Macintosh. 


Spam will allow DOS partitions on SCSI disks and CD-ROMs. Currently Apple File Exchange 
cannot handle large DOS disks. 


Dependencies 
¢ Disk Initialization Update — In order to accomodate initialization of disks to the DOS 


format, Spam requires the presence of the new-Bisk Initialization interface which allows foreign 
file systems to become an option for users whenjerasing/disks. 


e Do we want to include the name ¥‘MS-DOB8”’ in the untified volAme name? Is it 


° By supporting an “empty” desktop database, does the Finder provide the DOS disk with 
enough icons and application mappings so that the disk appears natural? 


° Should we support comments on writable disks? 


° The SCSI Driver will need significant changes to allow for access to non-Macintosh 
partitions, notably DOS partitions. 
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User Interface 


Viewing a DOS disk 


We will first consider what a user can do with a DOS disk that has never been inserted into a 
Macintosh drive before. If the user is in the Finder the disk icon will appear as with any 
Macintosh disk. 


File Edit View Special 


will have the geneNc name Ati . Otherwise] we would display the DOS label 
as the volume name&_When a DO pened, the files are displayed within the 


re 
VL ru 
3 i 


123.CMP 123 .CNF 123.COM 123.DYN = 123.HLP 


123.SET BLOCK1.FNT BLOCK2.FNT BOLDFNT CMLO3SO00.FCLCMLO300.HCL 


[roto] foro] [roto] lo10i| [roioi] froror] 


Figure 2. Some files from the Lotus 1-2-3 System Disk. 


Icons have already been devised for files under DOS and these are illustrated in figure 2. 
Since DOS provides no clue as to whether a file is binary, textual, or whatever, all files from a 
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DOS volume have the same icon. The extension part of the file name is just a hint as to the file 
contents, not an absolute statement. In such a case, it may be that the best way for someone who 
is familiar with DOS to view a DOS disk in the Finder is “by Name”—this is the closest to the 
DOS DIR listing. 


Untitled MS-DOS 
Size Kind Last Modified 


O 123.cmp MS-DOS document Mon, Mar 23, 1987 
CD 123.CNF MS-DOS document Mon, Mar 23, 1987 
Q 123.com MS-DOS document Mon, Mar 23, 1987 
Q 123.DYN MS-DOS document Mon, Mar 23, 1987 
D) 123.HLP MS-DOS document Mon, Mar 23, 1987 
D 123.SET MS-DOS document Tue, Jan 1, 1980 

1 BLOCK1 .FNT | MS-DOS document Mon, Mar 23, 1987 


CD BLOCK2.FNT MS-DOS document Mon, Mar 23, 1987 
CQ) BOLD.FNT OS document Mon, Mar 23, 1987 
CD) CMLOz00-FCL Tue, May 13, 198¢ 
D) CMLOZ00.HCL 

D cOoPYHARD.coM 


existed they would have\ been isplayed on the 
behave just as Macintosh\{folders“te 
close. 


Besides showing up normally under the Finder, a DOS disk is also seen through the standard 
“Open...” interface. Figure 4 on the next page shows such an interface from Microsoft Excel. 


I show Excel’s “Open...” dialog in Figure 4 on purpose: Excel is the canonical example of 
an application that can read a DOS file without prior translation. In this case, Excel can directly 
read Lotus 1-2-3 files and PC Excel files. Mac Microsoft Word can directly read DOS Word 
files (although the reverse is not true!) Other applications which have both Mac and DOS ver- 
sions (e.g., Multimate, Word Perfect) often have compatible file formats as well. 
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Open Document 
Untitled MS-DOS 
M 123.CMP Untitled MS-D... 
D 123.CNF a 126K available 


O 123.COM a 

D 123.DYN | 
D 123.HLP 

D 123.SET 

D BLOCK1.FNT 


Figure 4. Opening a file from Excel. 
Reading a file from DOS 


Spam has no tr 
tions try to understand the 


uble reading data frm DOJ disks. The problems arjse when Mac applica- 
at they read frpbm DOS disks. Excel angi Word are the excep- 
tris problem i . simplefext Pies, however, have a bit — 


of a problem. 
Figure 5 showsjthe probit . MPW reads it without problem, © 
but at the beginning.of/ ery line i chargtter box, drawn (among other 


times) when the Mac-s¢ con qr. | hi age cfaracter is a line feed (LF). All 


age 
etege. 

stegs 
Ha 


0 &&copst &&copst! !!SIBMOCPS-S1BM 1COT 
0 &&copse &&copste !!SIBNOCOT-SIBMICOT 
0 &&camsm &&camsm! |! !S1IBMOCMT-SIBMICNT 
0 &&camss &&camss! !!SIBMOCAT-SIBMICAT 
0 S&gridt &&gridti !!SGCOS-SGCIS 

OD &&tosht &&tosht! |!!STOO11IS-STO111S 

O &&toshtt &&toshtlt !!STOO31S-STO1IPHRS THE 


geass 


NM &RtashSNt RtashtsNa | tSTANPSN -STN1IPHRS Hae 
Figure 5. Reading a DOS text file using MPW. 
As another example, the next figure illustrates our big success story: Excel recognizes and 


automatically loads in the spreadsheet from Lotus. Figures, formulae, formatting, everything. 
The user doesn’t even have to know that file came off of a DOS disk. 
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REALTY.WK1 


| cL 

CURRENT LISTINGS 
BDRMS BATHS LOT 
0.25 
0.40 
0.60 
0.30 


WAN ANN N WOO 
NON—-~—- -“ NN A 


How a file “behaves” 
makes it possible for the a 
will look exactly the same as the 


Let’s look at a few examples. A user will be able to change the name of the volume to any 
legal Macintosh name (i.e., up to 27 characters, no colons). The figure on the next page illus- 
trates a DOS volume that has been given a longer, more descriptive name. 
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Figure 7. A more friendly (and legal) name for the DOS disk. 


A user will be also able to rename any files that appear on the disk. As usual, renaming 
them does not change the kind of file they are: the icons remain the same. 


My MS-DOS® Disk 
293 items S75K in disk 


papaverine SSS ann nnn een 


123 Compare File short NOTTEXT.TXT 123.DYN Help File 


Figure 8. We can assign any name we want to DOS files. 


A file can have a comment associated with it which is shown in the “Get Info” window in 
the Finder (see figure 9 on the next page). 


window it may be Yyse allittle-kyow : indey. When a disk supports 
“short names” for ffles,Jas does Ap pleShare 2.Q ang Wis possible for the user to 
click on the name a “Get Info” is short name. It is no 
coincidence that the short pame of a fil sau to file name that the file has | 
under DOS. 


Further discusstormwith the Fifder group is needed fo deterfnine if further assists are needed 
for users who wigh to knpw more about the actual filg names, It has been suggested that a new 


Locked [] 


Thurber Report 


Kind: MS-DOS document 
Size: 6,712 bytes used, 7K on disk 


- Where: Untitled MS-DOS , internal drive 
Created: Mon, Mar 23, 1987, 1:22 AM 


Modified: Mon, Mar 23, 1987, 1:25 AM 
Version: not available 


& book report on James Thurber's “My World 
and ‘Welcome To It" 
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Figure 9. A comment explains even better than a file name. 


Locked [_] 
Short Name: !Thurber Re 


Kind: MS-DOS document 
Gizea-> 6 7127 hites cad FK an dick 


Figure 10. It’s possible to see what DOS would have called the file. 


Creating and writing files on a DOS disk 


With Spam, files can be created and written onto the DOS volume without regard to 
differences between the Macintosh me DO jgure 11 on pane next page illustrates the fact that 
auser can copy any file fre digk to th¢B 


Should someone try t¢ i onto 4 DOS-—disk-there-is eason why they 
shouldn’t be able to doublk-cli kc on the application hd ¢ ‘ Spam allows just this 
sort of behavior. The fig pageshows a VV acintosh appficatigh that has been cop- 
ied over to a DOS disk. 


M1S-DO9® Disk 


“. Beale Cel om Ep 


MacPaint 123 Compare File short NOTTEXT.TXT 123.D‘YN Help File 


Figure 11. What’s a nice application like MacPaint doing in a place like this? 


A more likely behavior is that a user will attempt to save (or “Save As...”) a file to a DOS 
disk. In the aforementioned Lotus/Excel example, this is exactly the desired result, as illustrated 
in figure 12. 
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Untitled MS-DOS 
i 2 23.0MP 
fy 123.CNE 
 223.00M 
 123.09N 


PS P23.HLP 


Save Worksheet as: Untitled MS-D... 
REALTY.WK1 126K available 


ONormal © SYLK 
O Text @ WKS 


the above figure shq file with ajname that conforms to 


As shown in the previous figures, when\nothing else 6 know/ about a file (i.e., on a “virgin” 
DOS disk straight gfit of PC), all files showed up withAhe samf 
into account the DOS filg name. Although DOS file name 
extensions are not\alway acotrate refi¢ction of thd file typ¢, they are still a good hint and we 


(QQ 
° 
=) 
Nn 
io) 
=) 
Oo 
o 
=) 
[on 
° 
Lary 
bot) 


ogee 
gotege 
seege 


123.COM 


cS iS LS fe ed b bd La 
REE RE 
SAMPLE.C SAMPLE.P SAMPLE.A REPORT.TXT README.DOC REPORT .DOC |i: 


soeses 
sists 


123.DYN 123.HLP 


Figure 13. What a DOS disk could look like if we take advantage of the file name extensions. 


Spam will allow the user to provide mappings between the DOS extension and the 
Macintosh file type and creator. In other words, we can guess that for a certain filename 
extension (for example, ‘“.WKS”) there is an appropriate Macintosh application to open that file 
(perhaps, Microsoft Excel or Lotus Jazz) and a particular file type that the application would like 
to see that file as. Apple can even provide a default set of mappings for well-known and popular 
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file types. 


The mapping of DOS filename extensions to Macintosh types and creators will be controlled 
by the user through a control panel item known (for now) as the Spam CDEV. By using this 
CDEYV, the user identifies what application should open a file with a particular extension, and 
even what icon should be used to display the file. 


Control Panel 


MS-DOS files and assigned 
Mac icons 


otegss 


WKS 
(MS Excel) (MS wars Doc) 


and application. 


: extetsion. For example, the ex- 
tension COM identifies an execiitable DOS program. These types are not assigned by Microsoft 
in the way the Macintosh filetypes are registered by Apple’s Developer Technical Support. 
Instead, there seems to be an informal registry system in the DOS developers world. For the 
most part, unique extensions are maintained. Also, there is no mechanism in DOS to prevent a 
user from giving a filename an inappropriate extension. 


The information that Spam needs to map filename extensions to Mac information is con- 
tained in a file called “DOS Preferences” that is created and maintained by the Spam CDEV. 
(Note: “DOS Preferences” may end up as a resource in the final version). At Spam initialization 
time it reads in the preferences file and creates private data structures that describe the extension 
mapping. Therefore, changes to the mapping preferences are not reflected in the Finder until the 
system is restarted. 


The Spam CDEV 


The control panel item (CDEV) that allows the user to change file extension mappings is 
sketched out on the next few pages. Keep in mind that the underlying purpose of this mapping is 
to assign a Macintosh type. and creator to a DOS filename extension. To the user it may appear 
that the she is simply finding a suitable icon, when in reality its the filetype and creator that are 
important. The icon just comes along for the ride. When the user selects an application and an 
icon, she is implicitly selecting a filetype and creator. 
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As shown Figure 14, the CDEV’s main window provides a list of DOS extensions and asso- 
ciated applications and icons. If the user wishes to add a new mapping, she is first prompted for 
the DOS extension, as shown in Figure 15. The user can type in a file name extension directly, 
or they can choose from a list of common extensions. 


Select an MS-DOS 
filename extension 


a part seis prompted Zo selgct the application that will 
actually open files qnding in . This is illustrateg/elow‘in Figure 16. 


§ ending in .THT 


c= Calvin 


C archives 
CC AudioCD FST vt.iF 1 ane 
CO BINLFST «—«—-—_ EEE anenresenenetnnnnnnnentnnnntntn 
C Development 

© Documents 
COMPU 

© Newest Audio CD 
© Pixel Paint 


[ Application | 


Figure 16. An application is selected to open files of a certain extension. 


Finally,the user is asked to choose which of the selected application’s icons to display for 
files with the given extension. See Figure 17. 
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Choose icon for (files ending .TXT) 


MacWrite Documents 


Creator: MCWT Type: TEXT 


Figure 17. Now we select which of the icons to display for the files. 


By giving the user a series of modal dialog boxes, we lead her ee the process of select- 
ing a type and creator without revealing the nasty details. 


To edit a mapping, the user is presented with a dialog which allows ‘tem to selectively 
change either the application which should open-the file, and/or the icon to ‘acacia for the file. 


See figure 18. 
Rexuten bad THT i= 7 


icon for 
Docume 


mits. dear 


Figure 18. The user can change the desired application or icon. 


Desktop Appearance 


Spam will not normally store icon information on a DOS disk inserted into a Macintosh. 
However, since the Finder uses the desktop information on other volumes available to it (the 
system disk, any other disks attached, AppleShare volumes) and provides the missing informa- 
tion from there, things will look normal. 


However, in the case that a user moves a disk from system to system the icons might change 
as different Macs have different sets of desktop information. If an Excel document is transferred 
to a DOS disk, the Excel icon appears as long as the disk remains on its original system. If the 
disk is taken to another Macintosh system which does not have Excel, however, then the docu- 
ment will not have the Excel icon (Macintosh disks remember such icons, even if the parent ap- 
plication is not around). This seems a reasonable price to pay, expecially since DOS disks are 
not likely to be used for file transfer between Macintosh volumes, and in this way the lower ca- 
pacity disks are not burdened with storing desktop info. For write-protected volumes (such as 
CD-ROM) this is the only choice. 
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Programmatic Interface 


This section discusses how MS-DOS files and volumes will appear to an application. The 
term “MS-DOS file” refers to a file written on an MS-DOS disk by an MS-DOS machine. An 
MS-DOS file therefore has no Finder information or HFS information available for it. An MS- 
DOS disk which has never been mounted by a Macintosh has only MS-DOS files on it. The 
term “MS-DOS volume” has an analogous meaning for volumes. 


In contrast, an “Macintosh file” refers to a file written by the Macintosh onto a disk (either 
HES or MS-DOS). It has a full complement of Finder and HFS information. On MS-DOS disks, 
this extra information is stored in a second file separate from the “normal” data file. See the sec- 
tion on “Effects on MS-DOS Disks”. A Macintosh file will always appear to an application ex- 
actly as if it had been written on an HFS volume. 


An MS-DOS volume and MS-DOS files are accessed via the MS-DOS FST in exactly the 
same way as Macintosh files are accessed from an HFS volume. Since they do not have Finder 
‘nformation nor HFS information, it is necessary to create or “synthesize” this information from 
the information which does exist in the-AfS-DOS file structures. The following sections discuss 
y e ‘ TDACKE #5-DOS file structures is 


5 ° 
presented, in order fo understand where the infor 


ing MS-DOS vglume formation. We will first look — 
at the data that is avafable from\MS-DO§. From The MS-DQS Encyclopedia, pp. 95-96, we 
i : i mati i : ector and the BIOS Parameter 


Bytes per secior 
The number of bytes per logical sector on the disk (also known as “sector size”). Typically 
the sector size is 512 bytes. It must be a power of 2. 


Sectors per allocation unit 
The number of contiguous sectors that form an allocation unit (or “cluster”). Typically for 


double-sided floppy disks, the cluster size is 2, while hard disks can have anywhere from 8 to 32 
sectors per cluster. It must be a power of 2. 


Reserved sectors, starting at 0 
This is the number of sectors reserved at the beginning of the disk, usually for the boot 


sector. 


January 13, 1989 Blue Book Edition Apple Confidential 


Page 14 . Spam Spec 


E9 XX XX or EB XX 90 


OEM name and version (8 bytes) 


Bytes per sector (2 bytes) 
Sectors per allocation unit (1 byte) 


$00 


$03 


$0B 
$OD 
SOE 
$10 
$11 
$13 
$15 
$16 
$18 
S1A 
$1C 
$1E 


Reserved sectors, starting at 0 (2 bytes) 
Number of FATs (1 byte) 

Number of root-directory entries (2 bytes) 
Total sectors in logical volume (2 bytes) 
Media descriptor byte 
Number of sectors per FAT (2 bytes) 

Number of heads ( 
i A ee ae 
oa ber of hidden sectors (2 by Rs) / 

® I mmmessesan tt 


CO | 


Figure 19. Boot Sector and BIOS Parameter Block (BPB) 


Number of FATs 

The number of File Allocation Tables stored on the disk (FATs). From The MS-DOS 
Encyclopedia, p. 97: “The file allocation table provides a map to the storage locations of files on 
a disk...Additional copies of the FAT are used to provide backup in case of damage to the first, 
or primary, FAT; the typical floppy disk or fixed disk contains two FATs.” 


Number of root-directory entries 
The number of 32-byte file entries in the root directory. The root directory size ordinarily 


depends on the type of device; a single-sided floppy disk can hold 64 entries, a double-sided disk 
can hold 112, and a fixed disk can hold 256. 


Total sectors in logical volume 
The total number of sectors on the volume. This is called the “logical” volume because there 


may be several volumes (partitions) on a particular disk (usually a hard disk). Note that this 
value is only two bytes, so the largest logical volume supported by MS-DOS is 65536 sectors x 
512 bytes/sector = 33,554,432 bytes or 32 Mbytes. (Note: Version 4.0 of MS-DOS, announced 
July 19, 1988 has broken this barrier). 


Media descriptor byte 
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The media descriptor byte (which also appears in the first byte of the FAT) is used to 
indicate the type of medium currently in a drive. The following table is from The MS-DOS 
Encyclopedia, p. 96. 


Descriptor ' Media Type MS-DOS Versions 
$F8 Fixed Disk 28 

$F9 3.5-inch, 2-sided, 18 sector 3.2 

$F9 3.5-inch, 2-sided, 9 sector 3.2 

$F9 §.25-inch, 2-sided, 15 sector 3 

$FC 5.25-inch, 1-sided, 9 sector 23 

$FD 5.25-inch, 2-sided, 9 sector 2,3 

$FE 5.25-inch, 1-sided, 8 sector 253 

SFF : 5.25-inch, 2-sided, 8 sector 1 (except 1.0), 2, 3 


Number of sectors per FAT 
The number of sectors used in each FAT. This is a function of the number of sectors on the 


volume and the cluster size. 


Volume label (not in BPB) 

In addition, a fABéT Tortie Volume jay be found i he Toor aire 
section below). Thijs label, although it ig stored/in the same 11-character 
not assumed to hav¢ a period-_hetween- the eight and minth-eharactyrs (4 


for the volume (see 
field as a file entry, is 
iles do to separate the 


J 


When returning volume iniprmation| about an volume via PBGetVInfo or 


PBHGetVInfo, the soTfOwing mappjng will He used: 


ioVDrviInfo, ioVDRefNum, 
io VFSID 
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ioNamePtr Points 4 the name/which ig stored as a label for the volume. 
Alabel is storéd, then feturn ‘UNTITLED MS-DOS’ as 
He name. 
' joVCrDate The time and date of the file which has the earliest 
creation/modification date (determined at mount time). 
io VLsMod The time and date of the file with the most recent 
creation/modification date (kept track of as the volume is 
updated). 
ioV Atrb Contains the volume attributes, i.e., if one or more files are 
open on the volume, and whether the volume is locked (and 
if so, locked by hardware or software). 
ioVNmFls The number of files contained in the root directory, or, if the 
refnum in ioVRefNum refers to a working directory, then the 
number of files contained in that working directory. 
io VBitMap First block of first volume FAT table. 
io V AllocPtr Set to zero. 
ioVNmAIBlks Number of clusters on the disk. 
io VAIBIkSiz Size (in bytes) of the clusters on the disk. 
io VClpSiz Same as ioVAIBIkSiz. 
ioAIBISt The block number of the first cluster. 
id VNxtCNID Set to zero. 
io VFrBlk The number of free clusters on the disk. 
io VSig Word Set to appropriate HFS signature by Spam. 


Set to appropriate value by Spam. 
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ioVBkUp Set to zero (There is no way to determine when the last 
backup was made). 
ioVSeqNum Set to zero. 
io V WrCnt Set to zero. 
io VFilCnt Number of files on the volume 
ioVDirCnt Number of directories on the volume. 
ioVFndrInfo Set to zero (all 32 bytes). 


File Information for an MS-DOS File 


The Macintosh has a rich set of file information fields in its catalog, part of which is not 
available from the MS-DOS file entry. First we will look at the data that is available from MS- 


DOS. From The MS-DOS Encyclopedia, pp. 281-283, we illustrate in Figure 20 a description of 
a file entry. 


Byte 
$1A SIC. SIF 
a2 oe 
11 bytes byte long word 
Name | 
The name is the famous Uinfamous?)\FILENAME.EXT forpat leftfver from the CP/M file 
system. A filename has tw6 pat ign. The/filename is at most eight 
characters, and the extengion is gt most stored as/11 charActers (spaces pad out the 
two parts if they are not Yomple , but ughally repregented wjth a period uaa ea the 


MS-DOS name is a legal Macit Ost-Rar 


MS-DOS has a limited set of file attributes available in its directory entry. From The MS- 
DOS Encyclopedia, pp. 282-283, we have the following for file attributes: 


7 6 5 4 3 2 1 0 
Sub- Volume Read-only 
(Reserved) | (Reserved) Archive directory label System file | Hidden file File 


Figure 21. The bits for file attributes under MS-DOS. 
Read-only File 
This attribute maps directly to the locked attribute of HFS files. This locked 
attribute is manifested in the Finder by the little locked icon and the check box in 
the “Get Info” window. In a PBGetFileInfo call, this locked attribute is 
manifested by setting bit 0 of the ioFlAttrib field. 
Hidden file 


This attribute is similar to the invisible attribute of the finder flags (bit 14). 
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On MS-DOS machines, it is used to indicate that this file should not be listed on 
normal directory searches. This can be overridden, however, and the user can put 
an option on the directory listing that says to display even hidden files. On the 
Macintosh, the Finder will not display files with the invisible attribute set and 
there is no defined way to override this. (Note: knowledgeable users can see 
these files in a Standard File listing in such utilities as Apple File Exchange, 
Resedit, and Fedit). 


System file 


This attribute is only vaguely similar to the System attribute of the finder 
flags (bit 12). On MS-DOS machines, it is used to indicate that the file is used by 
the operating system. In a manner similar to the “hidden file” attribute, files with 
this attribute are not displayed in normal directory listings. On the Macintosh, the 
Finder does display files with the System attribute, but queries the user if they are 
“sure you want to throw away the system file” in question. In addition, it appears 
that the Finder prevents the names of such files from being changed. 


Volume label 


hy have names, 


ot have ngme As” 9 they are called). 
se label is stored the sarpé as affile entry in the root 
“volume label” bi Mil other attributes are 


: dnted in a similar manner to 
ProDOS and of Syste ory tered as a file entry in its 
parent directory, with this “subdirectory” bit set in the attributes field. The 
location information is then interpreted as pointing to another directory list 
instead of pointing at the beginning of a file. Although Macintosh subdirectories 
are implemented in a substantially different manner, the functional mapping 
between MS-DOS and Macintosh subdirectories is fairly direct. 


Archive 


On MS-DOS machines, whenever a file is opened, written to, and closed, 
the “archive” attribute is set in its file entry (it is not sufficient to set this bit by 
just opening the file, reading from it, and closing it). Unlike the Macintosh file 
system, MS-DOS keeps only one time-stamp per file, which is updated whenever 
it is written to. The “archive” attribute thus makes it possible to tell if the file has 
been written to since creation, and—assuming some backup mechanism which 
clears this bit—whether the file has been written to since the last backup. The 
Macintosh keeps time-stamps for creation of file, last modification, and last 
backup. 


Time/Date 

The time and date fields initially indicate when the file was created. Whenever the file is 
written to, these fields are updated to reflect the new time. Due to the structure of the MS-DOS 
time-stamp, the time/date is accurate to within 2 seconds (as opposed to 1/60th of a second for 
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Starting Cluster 
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This field is very similar to the ioFIStBlk field that was used under MFS; it is the starting 
Cluster for the file (a “cluster” is the same as an “allocation block” on the Macintosh). For HFS, 
however, the ioF1StBlk field is always set to zero. 


File Size 


‘The file size is a long word, indicating the logical size of the file in bytes. The physical 
size can be deduced by rounding up to the nearest cluster size. 


Returning Information About an MS-DOS File 


When returning file information about an MS-DOS file via PBGetFInfo, PBHGetFlInfo, or 
PBGetCatInfo, the following mapping will be used: 


ioNamePtr 


ioFRefNum 
ioFlAttrib 


ioFlFndrInfo 
fdT ype 


fdCreator 
fdFlags 


fdLocation 
fdFldr 
ioDirID 


ioF1StBlk 
ioFlLgLen 
ioFlPyLen 


ioFIRStBlk 
ioFIRLgLen 
i0FIRPyLen 
ioFlCrDat 
i0FIMdDat 
i0F1BkDat 
ioFXFndrInfo 
ioF1ParID 


i0FICIpSiz 
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Points to the name in the classic MS-DOS FILENAME.EXT 


Set tc to 7er0. 

Return the “file size” from the MS-DOS file entry. 

Round whatever is in ioFlLgLen up to the nearest cluster size 
(see the Notes on Volume Attributes). 

Set to zero. 

Set to zero. 

Set to zero. 

Return the Time/Date from MS-DOS file entry minus one 
second, 

Return the Time/Date from MS-DOS file entry. 

If the “archive” attribute from MS-DOS is set, then return the 
backup date the same value as the creation date. If not, then 
return the same value as the modification date. 

Set to zeroes. 

Set to the directory ID of the parent directory (see the Notes 
on File Numbers and Directory ID's). 

Set to zero (the volume clump size will be used). 
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Effects on DOS Disks 


The overriding goal of Spam is to provide a seamless integration of DOS disks into the 
Macintosh world when the disks are inserted into the Macintosh system. When a compromise 
must be struck between surprising the Macintosh user and the DOS user, the scales are always 
tipped against the DOS user. However, since the DOS user and the Macintosh user may be one 
in the same, it is essential that we do not make the DOS disk impossible or even difficult to use 
after it has been to visit a Macintosh. 


File Names 


When a Macintosh file is created on a DOS volume, it is sometimes necessary to massage 
the file name to conform to the DOS standard of eight characters followed optionally by a three- 
character extension. AppleShare has already defined a standard for converting Macintosh names 
to what they call “short names.” Although this standard is not documented anywhere, it is imple- 
mented in AppleShare 2.0. The following gives a flavor of the method for converting names. 


If the Macintosh name is le DOS, then the DOS name is identical to the Macintosh 
name. 


If the Macintdsh nam is not Jegal under DOS, th¢n a DOB name is synthesized by looking 
at the first ten characters\of the . Qo indicate hat the fame is synthetic, an exclamation 
point is used as theNg eéxclamation point is 4 legal but uncommon character in 
DOS file names). If tit aracters contain“justtetters and numbers, then an artificial 
break is made where the DOS extension would be. International characters are mapped to stan- 
dard ASCII characters. 


Macintosh Name DOS Name 
Departmental Report !DEPARTM.ENT 
Laserwriter ILASERWR.ITE 
MacProject {MACPROJ.ECT 
Skal !Skal 

SkivSékare {SKIVSOK.ARE 


If the first ten characters include spaces, then adjustments are made to where the artificial 
break occurs, if the space occurs toward the end of the name. Otherwise, an underscore indicates 
that a space was in the name. Characters which are illegal under DOS are dropped from the 
name. —~ 


Macintosh Name DOS Name 
Screen 0 !SCREEN.O 
Annual Report !ANNUAL.REP 
Tiny Report ITINY_RE.POR 
This is a test !{THIS_IS.A 
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3/4 Time 134_TIME 
*Status* ISTATUS 


In some cases, two different files may synthesize the same name. When this occurs, the last 
character of the file name is replaced with a digit which is increased until no conflict appears. 
The following list gives an example: 


Macintosh Name DOS Name 

Laserwriter Fonts ILASERWR.ITE 
Laserwriter !LASERWR.ITO 
Laserwriter Prep !LASERWR.IT1 
Laserwriter Download {LASERWR.IT2 


Creating Macintosh Files 


The DOS file structure is a descendant of CP/M and inherits many of the latter’s limitations. 
The Macintosh Hierarchical File System has a much richer set of information about each file, as 
well as a multiple-fork storage mechanism. In order to simulate HFS without breaking the DOS 
structure, additional information needs to be ptexed in different places on the DOS disk. 


into two separate DOS at BS, with the oe file confainhhg ie resourgé fork along with other 
file information. In any directgoyv RpleDouble'file resides 


each AppleDouble file. 


As an example, Figurg ample DOB directory (PA T.DIR”) which contains 
four files. The next fig igu ows the same direc Ory afte¥ two Macintosh files have 
been created on it, “Departmental Repp f 
panded to include not on\ the neW data files/but also the fubdirec ory “!!RSRC.FRK”, which 
contains the AppleDouble cotméexpz ute 


MS-DOS Directory As seen on the Macintosh 

PARENT.DIF PARENT.DIR filetype creator 
REPORT. TXT BUDGET.WKS BINA mdos 
BUDGET .WKS EMPLOYEE.DBF BINA mdos 
EMPLOYEE. DBE PRIVATE.DAT BINA mdos 
PRIVATE.DAT REPORT.TXT BINA __ mdos 


Figure 22. A subdirectory on both DOS and Macintosh. Just DOS files. 
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MS-DOS Directory As seen on the Macintosh 

PARENT.DIF PARENT.DIR filetype creator 
REPORT. TXT Annual.Rpt XLBN XCEL 
BUDGET .WKS BUDGET.WKS BINA _ mdos 
EMPLOYEE. DBF Departmental Report WORD MACA 
PRIVATE. DAT EMPLOYEE.DBF BINA mdos 
!DEPARTM.ENT PRIVATE.DAT BINA mdos 
!!RSRC.FRK |. REPORT.TAT _ BINA mdos 

!DEPARTM. REP . 
i ANNUAL.RPT 

ANNUAL. RPT 


Figure 23. Same subgise@tory with two Macintosh files added to it. 


The !!APPLE.MA€ —a parallel direcfory structure. 


The AppleDoutle fifes that are stored i in th !!F 
vide Macintosh infarmalior ve 
can more time-consuming than desired i 
Therefore, if there’y roomy ie D OS FST adds a special filg called 
contain a copy of thé-¥#lume’s dirdctory stricture (also cafled a° forallel directory structure’ Ni as 
well as a copy of the-file informatipn which| would normally haye to be synthesized or retrieved 
from the AppleDo ; 


6RC.FRK supdirecrOry are sufficient to pro- 
formation about such a file 


Pi CHEE 
oe creation order), it is a desirable feature. If there is not see room to build the 
“!!APPLE.MAC” file, then file information can be retrieved by way of the AppleDouble re- 
source file, although at the cost of performance. 
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- Introduction 

This section describes HFS enhancements planned for the Big Bang System release. These en- 
hancements consist of several components including File Links, a BTree Manager, a Catalog 
Search facility, and other enhancements. All of these enhancements are required in support of 
one or more other Big Bang projects. In general, these features enhance Macintosh’s ease of use 
with respect to the retrieval of a user’s files or data. 


The following paragraphs give an overview of the functionality of each of the individual en- 
hancements and how they relate to Big Bang. 


File Links 

The overall purpose of File Links is to enhance Macintosh’s ease of use with respect to the re- 
trieval of a user’s files. This is accomplished by providing a kind of “permanent address” for any 
file regardless of j DOSI older hie is permits applications to 
“remember” a filejso that, even if i a different folder, the file 


@ 
dori 


od-tona oe 34 is déne in spreadsheets (Microsoft 
Excel), data bases| (HyperCard, 4th Diq ension etc.), and Sther Applications. File Links provide 


Two major compenents of the] Big Bang System Aoftwafe Release depend on File Links. 
i owever, it is easy to imagine how 


BTree Manager ; 
The BTree Manager is a basic keyed access method for HFS data forks, providing efficient data 
access through the use of HFS’s internal BTree package and disk caching scheme. 


The BTree Manager provides an important “building block” to both internal and third party de- 
velopers who have a need for keyed data storage but don’t need the generality or capacity of a 
comprehensive data base. The BTree Manager will be especially useful in cases where the 
Resource Manager is used (albeit inappropriately) as a data base and is a limiting factor in terms 
of space or speed. 


Big Bang components using the BTree Manager are Diet Coke and the Finder. 


Catalog Search 
The catalog search facility, CatSearch, is a new HFS function that permits high performance 
flexible searching of an entire HFS disk catalog. 


CatSearch will enhance the performance of any application oriented toward processing entire 
volumes, such as a backup application or a “Find File” facility. It will permit such applications to 
quickly process an entire disk’s catalog to select files based on a comprehensive set of key crite- 
ria. 


a aa a ee 
Apple Confidential Page 1 


January 12, 1989 HFS Enhancements 


The main Big Bang consumer of the new HFS CatSearch facility is the Finder. 


Other Enhancements 


Several other HFS enhancements that are under consideration but which are currently unstaffed 
include: 


¢ Catalog Extensions 


This would permit the storage and retrieval of extended information for files and 
directories. 


¢ International Catalog Support 
This would permit the sorting sequence of file names to be customized as to case 
and diacritical sensitivity on a per-volume, per-country basis. 


* Remote Booting 
Some support of the Remote Booting effort will be needed to insure smooth inte- 
gration of the Remote Booting AppleShare components with the File System 
Manager (File System Manager mu ide in ROM for Remote Booting to work). 
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by Joe Buczek 
January 12, 1989 


Introduction 
This section describes what File Links are, the programmatic model they present, and the addi- 
tional HFS functions that are needed to create this new capability. 


Purpose 

The overall purpose of File Links is to enhance Macintosh’s ease of use with respect to the re- 
trieval of a user’s files. This is accomplished by providing a kind of “permanent address” for any 
file regardless of its name or position within the folder hierarchy. This permits applications to 
“remember” a file so that, even if its name is changed or it is moved to a different folder, the file 
may still be located quickly and automatically. . 


This document does not describe a 
File Links. 


y.af the possible Human Interface issues related to the use of 


Big Bang Depende 
Two major comp¢ 
through the use of] 


Properties ¢ 


Scope 
The scope of a File mite Hred-<within the volume that contains the link 
itself. A File Link on volume “fred:” cannot be made to refer to file on volume “wilma:”. 


Uniqueness 
The uniqueness of the value of a link is guaranteed by HFS such that a link value, once assigned, 
is for all practical purposes never reused. 


The phrase, “for all practical purposes”, in the paragraph above can be explained as follows: The 
value of a file link is a unique internal value used by HFS. To generate these, HFS increments a 
value kept in the volume header stored on every disk volume. Because this internal value is an 


unsigned 32-bit integer, keys would only be reused every 232 - | file creations. At present, creat- 
ing this many files would result in more disk writes than any device can perform without exceed- 
ing manufacturers recommendations for reliable operation (media or drive hardware would fail 
first). 


Permanence 
Once a link to a file is created, that link will always point to the target file until such time as the 
target file or the link itself is deleted. 


It should be noted that the behavior of most application programs is a problem when trying to 
make File Links work transparently underneath them. This is true because of the HFS functions 


sees ee ee a eee acecta w ae  e  a 
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normally used in implementing an application’s “Save”or “Save As...” commands. 


Typically, the file a user is saving is written to a “temporary” file, then that file is renamed to the 
desired name. If the rename operation fails (“Save As...” case), the user is prompted for confir- 
mation of replacing the existing version of a file. If confirmed, the application proceeds by delet- 
ing the existing file, then does the rename operation again. 


This above process would routinely destroy file links, so a new function is needed. The new 
function, dubbed “replace”, allows an application to replace an existing file’s contents and file 
attributes (type, creator, etc.) with a second file’s while keeping the link identity of the first file. 
This would atomically destroy the file’s previous contents, replace it with the contents of a sec- 
ond file, replace its file attributes, and then destroy the second file. For more on this, see the sec- 
tion called “Replace File” below. 


Format 
A File Link is stored as a 32-bit unsigned long word. No assumption can be made about the actu- 


al value of a File Link. It may only be interpreted as an arbitrary key for retrieving the file to 
which the link refers. 


File Links will be impler 


cessed on a oe that suppOrts File L ks. 


New HES Calls 


This section describes the programmatic interface to HFS File Links. Parameter block fields and 
offsets have not been determined yet, so only high-level language calls are shown. 


Create Link 
The “create link” call creates a unique link to an HFS file given a vRefNum, fileName, and 


dirID, . The actual value of the File Link is determined by HFS and is the result of successfully 
creating the link. 


FUNCTION HCreateLink (vRefNum: INTEGER; VAR fileLink: LONGINT; 
fileName: Str255; dirID: LONGINT): OSErr; 


Destroy Link 

The “destroy link” call invalidates a file link. Any instances of this link stored by any application 
become invalid. The next time any application attempts the “resolve link” call using the link 
value specified, a “file not found” error is returned. 


FUNCTION HDeleteLink (vRefNum: INTEGER; fileLink: LONGINT): 
OSELY? 
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Resolve Link | 

The “resolve link” call converts a valid file link to a dirID and a fileName. If the link specified 
has become invalid due to the file having been deleted or the link being destroyed (see above), a 
“file not found” error is returned to the caller. 


FUNCTION HResolveLink (vRefNum: INTEGER; fileLink: LONGINT; 
VAR fileName: Str255; VAR dirID: LONGINT): OSErr; 


Replace File 

The “replace file” call is used when an application wishes to perform the “Save As...” function 
while preserving any file links that may exists. Both the existing file and its replacement are 
specified. If the file cannot be replaced because it is open, an error is returned. The replacement 
file must exist on the same volume as the file being replaced. The file specified by destDirID and 
destName are replaced by the file specified by srcDirID and srcName. Both files must exist on 
the volume specified by vRefNum. 


FUNCTION HReplace(vRefNum: INTEGER; destDirID: LONGINT; 


destName: Str255; srcDirID: LONGINT; srcName: Str255): 
OSsEBrrs 
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by Kenny Tung 


Introduction 

The capability of the internal HFS BTree Manager has been extensively used by HFS in 
supporting the hierarchical catalog and file space mapping to improve file system performance. 
The internal HFS BTree Manager has really made our file system stand out against other 
microcomputer file systems. 


Because of the proficiency of Btrees in managing large databases, recently there has been a lot of 
solicitation from other groups asking for a generic interface with the internal BTree functionality. 
The purpose of this project is to export these internal routines so that the BTree functionality is 
available to general applications; and the New Finder in particular. 


Overview 
The BTree manager can|be viewed as a higher leve]/ keye 
a Btree contain records; Fach record consistsjof ce 

key associated with that informe 


Of HFS. The nodes of 
in information (either pdinters or data) and a 


For a detailed descriptigin of BTree plegse referfo chapter 9, volufne 4 of Inside rn 


BTree Manager Calls 
A BTree file is a specific organization of the data fork. It makes no sense to read its contents via 
a regular read routine; and a BTree file’s organization will be damaged if you write directly to it. 
Therefore, another set of functions are necessary for accessing BTree files. 


Most of these routines can be executed either synchronously or asynchronously, but some 
routines can only be executed synchronously for this release. 


All these functions return a result code, a zero means no error. Result code should be consulted 
after each call. In addition to the conventional File System's result codes, the following result 
codes are added for the BTree Manager: 


_ Name Yalue Meaning 
NotBTree -200 the file is not a BTree file 
BTsizeErr -201 the record size is too big 
BTFempty -202 no disk space has been allocated 
BTRecNotFnd -203 record not found search error 
BTdupRecErr -204 record already exists 
BTKeyAttrErr -205 unsupported key type 
BTKeyLenErr -206 key length to long 
BTMInvalid -207 invalid place marker 


Apple Confidential Page 1 


January 12, 1989 BTree Manager 
The result code values are picked arbitrarily for now. Appropriate values will be assigned later. 
The HParamBlockRec, described in the File Manager chapter of volume IV of Inside Macintosh, 
will be extended by the addition of two param block types, BTParam and BTIOParam as shown 
below: 


HParmBlkPtr = *HParamBlockRec; 


HParamBlockRec = RECORD 


qLink : QElemPtr; 
qType : INTEGER; 
ioTrap : INTEGER; 
LoCmdAddr = PEr? 
ioCompletion: ProcPtr; 
ioResult <“OSEEF; 
ioNamePtr : StringPtr; 
LoVRefNum : INTEGER; 

CASE ParamBlkType OF 

BTIOParam: 


LioBTHint : INTEGER; {place marker} 


LoBTPosMode : Byte; {position mode} 
ioKBufSize : Byte; {key buffer size} 
ioKActCount : Byte; {key actual length} 
fillerl : Bytel; 

BTParam: 
( LoDirID : LONGINT; 


ioBTRecNum : LONGINT; {total number of records} 
ioBTNodesize: INTEGER; {node size} 
ioBTKeyLen : INTEGER; {max key length in bytes} 
ioBTNNodes : LONGINT; {total number of nodes} 
iLoBTFreeNode: LONGINT; {number of free nodes} 
ioBTKeyattr. : Byte; {key attribute} 
filler : Byte]; 
(other Param definitions). 
END ; 


i a ee 


Apple Confidential Page 2 


January 12, 1989 


BTree File Initialization 


BTree Manager 


FUNCTION BTInit(paramBlock: HParamBlkPtr; async: BOOLEAN): OSEr; 


-> ioCompletion pointer 

<- ioResult word 

-> 1ioNamePtr pointer 

-> ioDirID long word 
-> ioBTKeyAttr byte 

-> ioBTKeyLen word 


BTInit initializes a new BTree file (the data fork), having the name pointed to by ioNamePtr on 
the volume specified by ioVRefNum. The BTree Manager supports the HFS pathname 
specification convention, that is, ioNamePtr can be pointed to either a full or partial pathname 
used in conjunction with ioVRefNum and ioDirID to specify a target file. The file should be 
already created and have disk space allocated for the data fork. If the file does not exist, a fnfErr 
error is returned. If there is no space allocated then a BTFempty error is returned.The newly 
initialized BTree file will be empty (contain no records). 


If you try to initialize a BTree file and t} 


file to empty state. (all Feécord 


This argument is usedlg 
plan to write your own 
the maximum length gf the Ke 


Opening a BTree File 


ompare rout\ne, then}you can ign 


le has already been initialized, BTInit will reset the 


e¥ comparison routine. If you 
J field. [OBTKeyLen specifies 
eter is NIL then BTInit does 


FUNCTION BTOpen(paramBlock: HParamBlkPtr; async: BOOLEAN): OSEr; 


-> ioCompletion 
<- ioResult 

-> ioNamePtr 

-> 10VRefNum 

<- ioRefNum 

-> i0Permssn 

-> ioBTKeyComp 
-> ioDirID 


pointer (should be NULL) 
word 

pointer 

word 

word 

byte 

pointer 

long word 


BTOpen opens the BTree file pointed to by ioNamePtr on the volume specified by ioVRefNum. 
As in BTCreate, ioNamePtr can be pointed to either 

a full or partial pathname used in conjunction with ioVRefNum and ioDirID to 

specify a target file. It checks to make sure that this is really a BTree file. If it is a BTree, a path 
reference number is returned in ioRefNum, otherwise it returns an error (NotBTree). 


Different from opening an ordinary file, when opening a BTree file, one new parameter has to be 
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passed in the ParamBlk, that is the ioBTKeyComp, which is a pointer to a key comparison 
routine used by the BTree manager for deciding the order of keys. When this BTree file is 
opened, BTree manager saves this information in its internal data structure. Through this 
mechanism, the user can define his/her own data structure for the key. If this parameter is NIL 
then the default compare routine is used. BTree manager provides a default comparison routine 
for users who don't want to write their own or for other reasons applications don't want to pass 
~ the comparison routine as an argument; this routine takes the key as a string and uses the OS 
Utilities RelString routine to compare the order of the two keys. In this case, the ioBTKeyAttr 
field must be passed with meaningful value. 


Note: BTOpen can only be executed synchronously for this release. 


Closing a BTree File 
FUNCTION BTClose(paramBlock: HParamBlkPtr; async: BOOLEAN): OSEr; 


-> ioCompletion pointer 
<- ioResult word 
-> ioRefNum ord 


Close the file arld removes the acces path/specified by ioRefNum\ All associated buffers are 
flushed to disk. is re Lif iti : pe file. You cannot close an 
open BTree file with PBClose because sonfe imernal struc fe to be flushed and memory 
has to be freed. | 


FUNCTION BTInsk Block: HParamBIRPtroasyhnc: BOOLEAN): OSErr; 
-> ioCompletion pointer 
<- ioResult word 
-> ioRefNum word 
-> ioBuffer pointer 


->ioReqCountlong word 
<- ioActCountlong word 


-> ioBTKeyPtr pointer 

<- 1ioBTHintl long word 
<- ioBTHint2 long word 
<- ioBTHint3 word 


This function is used to insert a record in the open BTree file specified by ioRefNum in the order 
sorted by ioBTKeyPtr. The record is built by using key and the data buffer pointed to by 
ioBuffer. The size of the data in the buffer is specified by ioReqCount . The file is expanded (by 
clump size) if necessary and if there is enough disk space. If the disk has no space to grow the 
file, an error (dskFulErr) is returned. Note that there is a limit on the size of data plus the key 
(see discussion below). If the record size is too big, an error (BTSizeErr) is returned and no data 
is written. 
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Upon a successful insertion, the ioActCount will contain the number of bytes actually written, it 
should match the value in ioReqCount field; and the ioBTHint (10 words) will contain a place 
marker within the BTree file where the record resides. The user can save this hint and pass it as a 
parameter when accessing the same record later on. The ioBTHint, when discreetly used, 
provides a cache mechanism that can speed up record look up. If you pass the ioBTHint 
parameter which involves a search operation, for example BTInsRec, BTDelRec, or BTSearch, 
the BTree Manager tries to locate the record using the hint. If the record is not found, then the 
regular search path (from the root) is resumed as in the case when the ioBTHint is zero. The 
ioBTHint could become invalid if there are any record insertions or deletions between the time 
you get the hint value and the time you use it later. Part of the place marker is a write count, 
-BTree Manager uses it for synchronization purpose to validate the hint. 


If the record you want to insert already existed, (i.e., a record in the file has the same key as the 
ioBTKeyPtr structure) an error (BTdupRecErr) is returned. 
FUNCTION BTSetRec(paramBlock: HParamBlkPtr; async: BOOLEAN): OSEn, 


-> ioCompletion 
<- ioRepgr 


-> ioBuffer 
-> ioReWCopnt long word 
<- ioActCopr sword 


This routine is the samt\as BTInsRec except that the created if it does not exist, or is 
replaced (overwritten) if it already-extfsts. See BT InsReCTor more detailed information. 


FUNCTION BTRep!Rec(paramBlock: HParamBlkPtr; async: BOOLEAN): OSErr; 


-> ioCompletion pointer 


<- ioResult word 

-> ioRefNum word 

-> ioBuffer pointer 
-> ioReqCount long word 
<- ioActCount long word 
-> ioBTKeyPtr pointer 
<-> i0oBTHint1 long word 
<- ioBTHint2 long word 
<- ioBTHint3 word 


This routine is the same as BTInsRec except that the record is replaced only if it already exists 
(not automatically inserted). Otherwise an error (BTRecNotFnd) is returned. See BTInsRec for 
more detailed information. 
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Retrieving Records 


The functions described in this section pertain to locating and retrieving records stored in a 
BTree file. 


FUNCTION BTSearch(paramBlock: HParamBlkPtr; async: BOOLEAN) : OSErr; 


-> ioCompletion pointer 
<- ioResult word 

-> ioRefNum word 

-> ioBuffer pointer 
-> ioReqCount long word 
<- ioActCount long word 
-> ioBTKeyPtr pointer 
<-> ioBTHintl long word 
<- ioBTHint2 long word 
<- ioBTHint3 word 


hat has a matching key (ioBTKeyPtr) from the open BTree 
RETIN —ttre“record| is found, then the data is 


transferred to thd data buffer poi 


actually read is fetumned inj the record is nof fousxd an error (BTRecNotFnd) is 


returned. If the file }afiot a B 


You can pass a saved BTHin} to spedd up the segrch. If/the record is found, a new hint is 
returned in ioB VF: | fay be diffefent frofn the one saved. This hint is used as a 
place marker pints to}the recgrd last afcessed. Wfth this pint, you can use BTGetRec call to get 


FUNCTION BTGetRec(paramBlock: HParamBlkPtr; async: BOOLEAN): OSEnr; 


-> ioCompletion pointer 
<- ioResult word 

-> ioRefNum word 

-> ioBuffer pointer 
-> ioReqCount long word 
<- ioActCount long word 
<- ioBTKeyPtr pointer 
<-> ioBTHintl long word 
<-> ioBTHint2 long word 
<-> ioBTHint3 word 

-> ioBTPosMode byte 

-> ioKBufSize byte 


<- ioKActCount byte 


BTGetRec searches for a record by using the place marker, which are ioBTHintl, ioBTHint2 and 
ioBTHint3, from the open BTree file whose access path is specified by ioRefNum. BTree 


wnt ere tas wales eg ws Pe Se Es cn ee 
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Manager gets the record pointed to by the BTHint plus the position mode specified by 
ioBTPosMode. Before getting the read, the write count in the BTHint is verified with an internal 
write count to validate the marker. If these two values don't match, BTGetRec will return 
BTMInvalid as its function result. You can use the ioBTPosMode field to select the previous, 
Current, or next record relative to the place marker. You can use the following predefined 
constants to set the position field: 


CONST btPrevRec =-1; {previous record} 
btCurRec =0; {current record} 
btNextRec =1; {next record} 


If the record is found, the data portion of the record is transferred to the data buffer pointed to by 
ioBuffer, ioReqCount has the size of the data buffer in number of bytes. If the buffer is too small, 
the data will be truncated. The number of bytes actually transferred into the data buffer is 
returned in ioActCount. The key portion of the record is transferred to the key buffer pointed to 
by ioBTKeyPtr, ioKBufSize has the size of the key buffer in number of bytes. If the buffer is too 
small, the key will be truncated. The number of bytes actually transferred into the key buffer is 
returned in ioKActCount. After the read is completed, the place marker is returned in ioBTHints. 


If the place marker points to the last recard,in the file a ee equals to btNextRec, 
BTGetRec moves the mre as its function result. 


Deleting Records 
FUNCTION BTDelRec(paramBlock: HParamBlkPtr; async: BOOLEAN): OSErr; 


-> ioCompletion pointer 

<- ioResult word 

-> ioRefNum word 

-> ioBTHint long word 
-> ioBTKeyPtr pointer 


This function deletes a record in the open BTree file specified by ioRefNum if the record has a 
matching key (ioBTKeyPtr). The file size remains the same but the internal tree structure is 
compacted. For this reason, when you want to replace an existing record, you should always use 
the BTReplace routine to perform the task instead of calling BTDelete and then BTInsert. Once 
the record is deleted, it cannot be retrieved. If the record is not found an error (BTRecNotFnd) is 
returned. If the file is not a BTree file, then a NotBTree error is returned. It may also return 
fnOpnEnr, ioErr, nsvErr, and rfNumErr errors. 


You can pass a ioBTHint to speed up the search process. 
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Miscellaneous 


FUNCTION BTGetInfo(paramBlock: HParamBlkPtr; async: BOOLEAN): OSEnr; 


-> ioCompletion pointer 
<- ioResult word 
-> ioRefNum word 


<-ioBTClumpsize long word 
<- ioBTKeyLen word 

<- ioBTDepth byte 

<- ioBTFreeNode long word 
<- ioBTNNodes long word 
<- ioBTNodesize word 

<- ioBTRecNum long word 


BTGetInfo returns information about the open BTree file specified by the ioRefNum. An error 
(NotBTree) is returned if it is not a BTree file. This function returns the file's clump size in bytes, 
the length of the key in bytes, the depth of the BTree, the number of free nodes available, the 
total number of records in the filgmand the node size in bytes in the fields of ioBTClumpsize, 
ioBTKeyLen, iqB¥Pepth;toBT. FReeNon amd Tob ENodesize respectively. 


Open issues 
1. Size limyé s descr{bed earlier/"A basic feature of the BTree is that data is 
stored only in the leaf no ich trans[Ates int¢ "the data in a BTree record is limited 


Phé currenyfnode size ig 512 byfes because of the size of the cache 
320 allow at Idast 2 recbrds, so a record is limited to (512 - 
node descriptor Si bytes per offset) 46 bytes. The user should be aware of this 
limitation. 


2. We may need to provide support in Disk First Aid or a new utility for compacting and re- 
pairing BTree files in the future. 


Appendix 


The following is an example of the key comparison routine (from existing ROM source). The 
extent file key has a structure like this: 


FXKey = RECORD 
keylength: _ byte; 
forktype: byte; 
filenumber: LONGINT; 
blocknum: INT; 
END; 


See Es oc es eS a a ne se eh Ss 
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Routine: FXMKeyCmp (FXM Key Compare) 


Function: | Compares two extent file keys 
; (a search key and a trial key). 


Input: AO.L - search key pointer 
: A1.L - trial key pointer 


; Output: DO.W - result code 
& +n_ search key > trial key 
; 0 search key = trial key 
: -n_ search key < trial key 


FXMKeyCmp: 
MOVEM.L_ AO-A1,-(SP)_ ; save registers 


2(A0),DO 
STYDC 


KCIsGT 


MOVE.W 6(A0),D0 ; compare block numbers 
CMP.W 6(A1),D0 


BHI.S KCIsGT ; search block # > trial block # 

BCS.S KCIsLT ; search block # < trial block # 
KCIsEQ | 

CLR.W DO ; result = "equal" 

BRA.S KCExit 
KCIsLT 

MOVE.W #-1,D0 ; result = "less than" 

BRA.S KCExit 
KCIsGT 

MOVE.W #+1,D0 ; result = "greater than" 
KCExit 


MOVEM.L_ (SP)+,A0-A1_; restore registers 
DO ; Set up condition codes 
RTS ; exit FXMKeyCmp 
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CatSearch 


Dave Feldman 


CatSearch is a new HFS call which allows applications to efficiently search any 
volume for files which match a specified selection criteria. The names and directo- 
ry ID’s for the files and directories that match are returned to the caller. The call 
supports multiple selection criteria, and allows a search to be broken up into many 
calls, allowing the caller to maintain good user response. 


Parameter Block 

--> pointer 12 ioCompletion pointer to completion routine 
--> word 16 ioResult result code 

--> pointer 18 ioNamePtr volume name 

--> word 22 ioVRefN vRefNum or WDRefNum 

--> pointer oe <9 aTTay Po = 

--> long word chCpunt aximum match 

<= long word 2 pcount = 


act e S 


~-> long word 
~—> CinfoPBPtr 
--> CInfoPBPtr 
--> long word 
--> long word 
--> long word 
--> long word 


values and J/ower bounds 
masks and 


catalg hint/, part 2 
catalj/g hing, part 3 


Result Codes 
noErr No Erre 
extFSErr External file system 
ioErr 1/O Error 
nsvErr No such volume 


paramErr <all sorts of reasons> 


Volume Specification 
IoNamePtr and iovRefNum are used in the standard way to determine the volume to 
search. 
Return Values 
IoMBu£Ptr points to the array where matching file and directory names are returned to 
the user. The array elements are of type MbufEntry: 
Const 
maxMatches = 30; { arbitrary array length } 
Type 
MBufEntry = Record 
ParID: longInt; 
CName: stxr31 
End; 
Var 
myMatches: array[1l..maxMatches] of MBufEntry; 
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Control Paramters 


IoReqMatchCount is the caller-specified highest number of matches to return. 
CatSearch assumes that the array pointed to by iomBufPtr is large enough to hold 
ioReqMatchCount entries. IoActMatchCount is the output parameter that is set to the actual 
number of matches found. The elements of the mBuf array up to and including the 
ioActMatchCount th element will be set to a file or directory name. The rest of the array (if 
any) will not be accessed nor modified. 


IoQuant specifies a limit on the number of file records to process. It provides a mechanism for 
the caller to place an upper bound on the run time of a single call to catSearch. IoStart1 and 
ioStart2 indicate where CatSearch should start searching from. To indicate that the search 
Should start at the beginning of the catalog the caller sets both to zero. To indicate that the 
search should continue from the location where the previous call stopped the caller simply leaves 
ioStarti and ioStart2 untouched in the param block from the previous call. 


The combination of ioQuant, ioStart1 and ioStart2 allows the caller to break a search of a 
catalog into several Cat Search which completes quickly. This allows the caller to 


provide good user response ducing a search: CafSearck processes file records until one of the 
following four conditions ig true: 


block full of searchable items, so T€CatSearch strategy is to use the same data structure which 
is output from PBGetCat Info (a CInfoPBRec) as input to CatSearch. Unlike Getcat Info, 
however, CatSearch uses two CInfoPBRecs, and limits their use to only the fields that make 
sense as search criteria. The various fields in the CInfoPBRecs are selected with bits in 
ioSpecBits. Each bit in ioSpecBits specifies a file or directory attribute that the search will take 
into account. The following constants are added together by the caller to make ioSpecBits: 


Const 
fsSBPartialName = 1; {substrings of names} 
f£sSBFullName = 2; {full names} 
£sSBFlAttrib = 4; {directories, locked files} 
fsSBFlFndrinfo = 8; {Finder file info} 
fsSBFlLgLen = 32; {data fork logical length} {files only} 
£sSBF1PyLen = 64; {data fork physical length} {files only} 
fsSBF1RLgLen = 128; {resource fork logical length} {files only} 
f£sSBF1LRPyLen = 256; {resource fork physical length} {files only} 
E£sSBF1CrDat = 512; {file create date} 
fsSBF1MdDat = 1024; {file modification date} 
f£sSBF1BkDat = 2048; {file backup date} 


fsSBF1XFndrInfo = 4096; {more Finder file info} 


fsSBDrUsrwds 


ul 
foe) 


{Finder directory info} 


Apple Confidential Page 2 


January 13, 1989 CatSearch 


fsSBDrNmF 1s = 16; {number of files in directory} {directories} 
fsSBDrCrDat = ole; {directory create date} 

fsSBDrMdDat = 1024; {directory modification date} 

fsSBDrBkDat = 2048; {directory backup date} 

fsSBDrFndrinfo = 4096; {more Finder directory info} 


All specified criteria must be true for a file or directory to be returned as a match. For 
example, if both fsSBFul1Name and fsSBF1lLgLen are specified, only files of a certain name and 
data fork logical size will be returned. Some constants are appropriate only for files and others 
are appropriate only for directories, and some are legal for both. Some constants have two 
names to match the naming conventions for CInfoPBRecs. 


Fields in cInfoPBRecs IoSpeci1 and ioSpec2 are used together to specify the search 
criteria. Different criteria use the fields in the two records in different ways. The date and length 
criteria use their fields ioSpeci1 and ioSpecz2 to hold the high and low values of a range. If the 
date or length falls within the low value in ioSpec1 or the high value in ioSpec2, the attribute is 
true for that file or directory. IoF1Att rib and the Finder info criteria use their fields in iospec1 
to hold their desired value and ioSpec2 to hold a bitwise mask indicating which bits in the field 
in ioSpeci are relevant to the currenysearch. If the value from a file or directory, after being 


true for that file or df e strin amePtr in ioSpec1. They 
are compared to thejna ctory pit 6mparison or an exact 
match comparison. ds of the c& ows 

Files: 

--> 18 pointer ioNamePtr pointer 

--> 30 ioFlAttrib byte 

-~-> 32 16 bytes ioDrUsrWds 16 bytes 

ioDrNmF 1s word 

--> 54 word 

--> 58 P word 

--> 62 ioF1lRLgLen long word 

--> 64 ioF1RLgLen long word 

--> 68 ioF1lRPyLen long word 

--> 72 ioF1lCrDat long word --> 72 ioF1CrDat long word 

--> 76 LoF1MdDat long word --> 76 ioF1MdDat long word 

--> 80 ioF1BakDat long word --> 80 ioF1BakDat long word 

--> 864 ioFlXFndrinfo 16 bytes --> 84 ioDrFndrinfo 16 bytes 


FsSBPartialName and fsSBFullName determine how ioSpec1*.ioNamePtr is used. If 
fsSBPartialName is specified, the string pointed to by ioNamePtr is used in a substring 
compare against each file and directory name. If £sSBFul1Name is specified, only exact matches 
will count. If both are specified, the search will be on the full name. All name comparisons are 
case insensitive and ignore diacritical marks. If either fssBPartialName Or fsSBFullName is 
specified and ioSpec1->ioNamePtr is nil or an empty string, paramErr 1s returned. 


If fsSBFlaAttrib is specified, ioSpec2*.ioFlattrib is used as a mask against the 
attribute byte from each file or directory, and this value is compared with ioSpec1*. 
ioFlattrib. If you set any bits in ioSpecl*.ioF1aAttrib other than bit 0 (locked) and bit 4 
(directory), you get paramErr. The other bits deal with file open/closed information, which is 
not part of the catalog. Note that future attribute bits may be defined so currently undefined 
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attribute bits must be set to zeroin ioSpec2*.ioFlAttrib. Note that the ioflaAttrib 
parameter allows searching for only files or only directories, based on bit 4. catSearch 
determines whether or not any file- or directory-specific parameters are legal based on the value 
of this bit. If fssBrlattrib is not specified, or if bit 4 of ioSpec2*.ioFlaAttrib is clear 
(masking out the value), CatSearch assumes that the search is to include both files and 
directories. 


If fsSBDrUsxWds is specified, ioSpecl.ioDrNmFls and ioSpec2.ioDrNmFls are as an 
inclusive range for the number of files in the directory. For example, if ioSpecl.ioDrNmFls is 
12 and loSpec2. ioDrNmF's is 27, directories with 12..27 files will match. The number of 
subdirectories is included. Specifying fssBprUsrWds in a search that includes files will generate 
a paramErr. 


If £sSBF1Fndrinfo is specified, ioSpec2*.ioF1Fndrinfo is used as a mask against the 
Finder info from each file or directory, and this value is compared with 
ioSpec2*.ioFlFndrinfo. FsSBF1XFndrinfo is similar to fsSBF1FndrInfo except that the. 
values used are from ioF1xFndrinfo. The constants fsSBDrUsrWds and fsSBDrFndrinfo have 
the exactly the same effect as their file-specific counterparts, since the information used is in the 
same place in the CInfoPBRec. Note howevorthat the Finder information has different meanings 


question. For example, if i 
logical lengths of 23...99 w 
search includes directories. 


MaxLongiInt are valid as the be? iwaix 
end) respectively. Using the same yale in iboth the ioSpecl ad ee will match only the 
exact date specified. FssBDrCrDat, fsSBDrMdDat and fsSBDrBkDat are provided for naming 
consistency only, as the infomation used comes from the same place in the cInfoPBRec. 


If the only criteria is fsSBPartialName Or fsSBFullName, ioSpec2 is ignored. 
Otherwise, if it is nil (or if ioSpeci is ever nil), paramErr is returned. 


CatSearch does not search the catalog in hierarchical order. Therefore it is useful only 
for searches of an entires volume. If a search of a directory is desired, then the matches from 
CatSearch’s global search must be filtered by the caller to eliminate matches that are outside the 
selected directory. 


CatSearch will be made available under AFP. To ensure proper access protection, AFP 
will postprocess the CatSearch call locally to ensure that matching records can be legally access- 
ed by the (remote) caller. 


Note: Currently CatSearch only works when called synchronously. However, the final 
version will operate both synchronously and asynchronously. 


Since CatSearch uses the CInfoPBRec for its search criteria, it will be very easy to 


Apple Confidential Page 4 


January 13, 1989 CatSearch 
acommodate future items if the definition of catalog information is expanded. 
Example 


For the following example, assume the declarations that have appeared so far, plus the 
following: 


myName: Str31; 

myParam: CSPBRec; 

mySpecl, mySpec2: CInfoPBRec; 
myError: OSErr; 

lengthl, length2: Longint; 


To do a search for file and directories on disk ‘Hard Disk:’ with ‘Dave’ somewhere in 
their name: 


myName := ‘Dave’; 
myParam.ioNamePtr := ‘Hard Disk:'; 
myParam.ioVRefNum := 0; 

myParam pioMB a 


ioReqMatchCount Matches; 


ioNamePtr := &myName; 


myParam 
myParam SBParti@iName; 
myError false); gotfresults } 
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Blue Virtual Memory 
"Big Blue" 


Bill Bruffey 
January 18, 1989 


Introduction 


This document describes a new Blue virtual memory facility. This new facility will be known as 
"Big Blue”. 


Big Blue is the virtual memory solution started by Phil Goldman last summer, and currently being 
developed by Phil together with Rick Daley. 


Note, this document is not a complete ERS, a complete ERS will be forthcoming at a later time. 
A general description of the virtual memory model provided by Big Blue is given first. This is 
followed by a terse description of the three possible implementations currently being considered. 
Virtual Memory Model 

"Big Blue" is a specific virtual memory solution targeted for the Mac OS. It utilizes a single 


address space shared by the entire machine, causing the machine to appear to have more physical 
memory than really exists. The Mac OS, Drivers, MultiFinder, applications, etc. are all faked out. 


Big Blue supports up to 8 MB of virtual mem 


ory, the maximum memory size for our current 
machines. This size limit Ganebe ementation ore 


ome 32 bit clean. 


possible, however, it is notfrequizect ti e be cor ée virtual memory. To 
increase performance Big ff 
directly during swapping. 
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The use of virtual memory/sTeatrolled by the usef via a Contfol Pangl interface. Using this 
interface, a user can enabJed/disabled vir nt of virtual memory to be 
used, and select the backikg stordvolup must be rebooted to enabled 


€. Oncefet up, the fnachine 
or disable the use of virtuaNnemory. 


Note that Big Blue provides no protection facilities. Protection is generally provided using 
multiple address spaces, one per process or task. 


Implementation Options 
1) collection of patches 


- prevent page faults at interrupt level 
- deferring execution of application code to non-interrupt level 
- we're responsible for patching all the holes = 


2) wrapper for old SCSI drivers 


- "fakes" re-entrancy for old drivers 

- localizes the patches 

- not proven to be workable 

- depends on third-party being cleanly written 


3) "Big Blue" friendly SCSI Manager and drivers 


- modify SCSI Manager to work without interrupts 

- modify SCSI drivers to be reentrant 

- third parties must rev drivers to use the new SCSI Manager 
- these new drivers can be positively identified 


MultiFinder 6.1 


Introduction 


This document describes the MultiFinder 6.1 which is the latest versionof the MultiFinder 
developed by Phil Goldman. It includes SADE support, set aside, support for a MultiFinder-only 
system, and large application support. 


The software for Mugt#tinder-6-+-is-etreagy in B 


A copy of Phil's latest ERS follows. 


MultiFinder 6.1 ERS 


MultiFinder 6.1 ERS 


User Interface Changes 
¢ Apple Menu Item Rearrangement/Extensibility 
(Dropped — not needed until newFinder) 


¢ Set Aside 

We will add an item that reads "Set Aside <xxx>", where <xxx> is the name of the 
application in which the apple menu exists. When the user selects this item, the 
application's windows are closed and a rectangular outline zooms from the outline of the 
application's frontmost window to the apple symbol on the left hand side of the menu bar. 

"Set Aside <xxx>" will be disabled if <xxx> is the only visible layer. 

When the user holds down the option key, "Set Aside <xxx>" flips to "Set Aside 
Others". In this mode all applications besides the frontmost are set aside. 

An application that has been set aside will not be brought to the front via the menu 
bar application icon (clicks in the icon in the right hand side of the menu bar normally 
bring each visible application to the front). However, selecting <xxx> from the apple menu 
of another application will zoom a rectangle from the apple menu title to the outline of the 
frontmost window of <xxx>, bring <xxjs=ip front of all other layers, and open all of the 
application's windowsfas tit e Oeiorefit was gevusicte 

There will alsoj be a "one-at-a-time} modeprovi 
user holds down the option-keywhileclic¥ing in fhe nemerbertee p 
switched out of will aytompticall side, with fo zooming rg€tangies. At the point at 
which the user has clidkedlerfOugh timex leave only one visibjé layof further clicks will 
cause the current applitation to-be set asidegnd the "next" setAside Ayer will be made 
visible, thus giving thd des#fed(?) oNe-at-a-tithe effect. 


ded as a set aside shortcut. If the 
ripene e application he 


6 facing MultiFindef in a snfall memory machine: 
accomodating very lakge appleatns (e.g AyperCard, FullWrife) and allowing larger 
numbers of reasonably Sized applications The immediate planfor alleviating memory 
woes is: 
* Include a mode in which MultiFinder quits all apps (including the Finder) and 

gets rid of itself in order to run one very large application. When the application quits, 
MultiFinder is restarted. Applications can take advantage of this feature by calling 
_Launch with the extended launch block and setting bit 13 (15 is SUBLAUNCH, 14 is 
TWITCHLAUNCH). The current Finder plan to utilize this feature is to only call the 
standalone launch when no other apps are running and the app in question has both min and 
preferred sizes > __TWMaxMen)(). 

Note that with this feature in place there is no reason not to have MultiFinder 
running all of the time. It allows the user all of the benefits of MF and the cost is never 
higher than that for UniFinder. 


New Services 
¢ New Events 
If the appropriate bit is set in the SIZE resource, the application will be eligible to 
receive a new event from _WaitNextEvent /_GetNextEvent /_EventAvail. 
¢ childDiedEvent An app has died 


Any app that has the receiveChildDied flag set in its SIZE resource will be notified 
of the death of any other app that it has launched. The high byte of the message field in the 
event record will be 253. The low word will contain the process id. 
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¢« New Launch Routine 
This routine has existed since MultiFinder 1.0, so there are no backwards 
compatibility problems. Its interface is: 


short 
MFLaunch(namePt, size, vVRefNum, taskMode, stack) 


StringPtr namePrr; 

unsigned long size, stack; 

short vRefNum; 
unsigned long taskMode; 


This routine will launch the app given by name namePtr in working directory vRefNum. 
The app's partition size will be size and its initial stack size will be stack. The taskMode 
parameter should have the flags as defined in the app's SIZE resource in the low word. The 
low bit of the high word should be set if the app has the AppleShare multiLaunch bit set. 
All other bits in the high word should be 0. 
The routine returns a process id if the launch was successful. If not, it returns 
an error <Q. Possible errors currently are: 


SYSERR -9 misc sys err 
TWITMEMERR i 
MEMFRAGERR 
CODEOERR 

APPMEMERR 


¢ New Wakeup Routine 
The format of this call 1s: 


short 
MFWakeup(pid) 
short pid; 


This routine will wake up the process specified by pid if it is asleep because the 
timeout on its last _WNE call has not yet occurred. This is useful for the entire class of 
applications that need to act on some "event" outside of those recognized by the OS Event 
Mer or by MultiFinder events. Previously these apps were forced to specify a small or zero 
timeout for _WNE and poll on the event. Now they can sleep forever, and have the code 
associated with the event call _MFWakeup. 

The most obvious example of this would be a communications app that does an 
async _Read on the serial port. It would like to sleep forever, and have the completion 
routine from the _Read call -MFWakeup. 

The method to check for MFWakeup is to check the version 2 __SysEnvirons record 
to see if the flag hasWakeup has been set. 

Note that to do this we would have to make the following (existent) routine public 
as well: 


short 
MFGetPIDQ) 


MultiFinder 6.1 ERS 


This routine exists if OSDispatch is implemented. 


« New Temp Mem Routines | 
The following routines have been added to the set of temporary memory calls: 


long MFTempGetHandleSize(Handle hdl, OSErr *pResultCode) 

void MFTempSetHandleSize(Handle hdl, Size newSize, OSErr *pResultCode) 
short MFTempHGetState(Handle hdl, OSErr *pResultCode) 

void MFTempHSetState(Handle hdl, short state, OSErr *pResultCode) 


These are the temporary memory counterparts of their respective standard memory 
calls. 


¢ Dynamic Memory Tracking 

This entails keeping track of the MultiFinder temporary memory requests that an 
application has made, and then disposing of any outstanding blocks when it terminates. 
Currently, applications are left to their own good graces; this does not cause a problem 
simply because few applications make use of the service. ..yet.. 

Note that since memory is tracked per application, this restricts the use of 
dynamic memory to applications oratas7 code running.onananplications behalf. In 
particular, drivers canrjot make temporary #hemory calls at accRun time i 
the memory across __GNE/_WNE calls. 


All Faceless ba \cati n the folder "Backgrfund Folder" in the 
System Folder will be Jaaghed when} MultiFipder starts uf. Only such application that 
Apple will provide is .J MultiFynder will lg e resource (‘STR ',- 


¢ MMU Support 
(Dropped) 


¢ ZDE Support 
(Dropped) 


¢ SADE Support 
- The new symbolic debugger runs only under MultiFinder. It requires specific 
support in MultiFinder. The following new routines have been added for SADE: 


short MFGetTrapAddress(pid, pTrapAddr, trapType, trapNum) 

short MFRecordTrapAddress(pid, trapAddr, trapType, trapNum) 

short MFReadWriteMem(pid, procMemPt,, cBytes, callerMemPtr, doRead) 

short MFReadWriteFPURegs(pid, callerMemPtr, doRead) 

short MFRegisterDebugger(pid, pEntryRoutine, pExitRoutine, pToAppRoutine, debugControlKeyCode) 


From the last routine, MultiFinder "knows" about the debugger's existence. It will 
"call" the debugger on interesting exceptions. When the debugControlKeyCode key is hit we 
will do a switch into the debugger, and give it a pseudo event informing it of what 
happened. 

All of these return a status word. O signals success and a subset of the errors 

defined for _MFLaunch above may be returned too. 

This is currently defined only for SADE. If there is sufficient interest we can make 
it public. 
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Introduction 


This document describes the MultiFinder enhancements currently planed for the Big Bang 
software release. The new version of the MultiFinder will be known as MultiFinder 7.0. 


Note, this document is not an ERS. It is a “blue” paper presenting our current understanding of 
this project. 


The key features of MultiFinder 7.0 are described below. This is followed by an IPC proposal 
developed by Jay Moreland. | 
MultiFinder Bifurcation 


This is a redesign and implementation effort to integrate the MultiFinder into our system, thereby 
removing its large collection of patches. Thestew design will layer the functionality that is 


g 
pe part of the M 


will make use of services pyoviged-by-—the 
of the system, rather than a¢ patches and.will be suitable 


. The piser interface layer will be 
WTese TAyvers will pe 
br integratioy R 


Inter-Process Communi 
mitting communication batween MultiFjAder prog 
Interprocess Communication Facility” below fof a descriptign of IPC. 


Improved MultiFinder Temporary Memory - This is a change to the MultiFinder temporary 
memory calls. MultiFinder temporary memory handles will be managed with the normal memory 
manager calls for handles (except for NewHandle). Also 


System-Wide Memory Management - fast memory allocation (no compaction) used by file 
system, graphics, printing?, etc. 


Additions to User Interface Layer 


Apple Menu Control - This allows an application (especially the Finder) to add items to the 
Apple menu. These items would invoke the application, and send it a message (see IPC above). 


Replacement For Puppet Strings - MultiFinder currently teases applications into opening 
documents, quitting, deactivating windows, copying the local scrap into the system scrap, etc. 
with a mechanism called puppet strings that simulates user events. The logical successor to this 
would combine the puppet string mechanism (for compatibility) with the new IPC mechanism, to 
allow new applications to better support these functions. 
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Print Puppet String - A new puppet string will tell an (already open) application to open, print, 
and close a document. Of course, an IPC equivalent would be created as well, for new 
applications. 


Shutdown/Restart - Finder currently includes code that uses the Quit puppet string to close all 
open applications, and then calls the shutdown manager to turn off or restart the machine. This 
code should be moved somewhere into MultiFinder so that non-Finder applications can do the 
same thing. 


Small Icon Support - Support for the “hand-tuned” small icons that the new Finder will support. 
This makes the icons in the Apple menu and the menu bar look much better. 


Enhancements to Both Layers 


32-bit Clean - This is cleanup required to make MultiFinder 32-bit clean. 


Improved DA Inter, sar interface to desk 
accessories. It imple r applications. Each desk 
accessory will have its own layer, and dgsk acce , aunched from places other than the 
System file. 
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Chapter 1 


Introduction. 


Applications 


Event Mechnism 


Netwo rk IPC 


_Gomm To OID OX| fore 


/ layer : 


SeOooCOC noo ceOCcont otis 


Fig ure 1. 


Interprocess Communications (IPC) is a low level operating system- 
mechanism that allows one application’ to send raw, uninterpreted data to 
another application. The IPC layer provides Apple and third party 
developers the necessary functionality to build multiple higher-level 
message based protocols. 


This ERS describes two interfaces to the IPC layer. 


The MultiFinder 7.0 presents new events to a MultiFinder 7.0 aware 
application?®. This interface hides details of the Operating System IPC 


1. Here application means double-clickable applications, drivers, CDevs, desk accessories and 
INIT style ‘dangling entities.’ 

2. Here and hereafter, until the next footnote, application means double-clickable application 
with a bit in the SIZE resource set appropriately. 

Wane eri oo eg te a 
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layer from the application. MultiFinder 7.0 will manage the Operating 
System IPC layer interface on behalf of the application. The MultiFinder 
7.0 Event extension is referred to as the IPC Event Mechanism. Currently 
under development is an InterApplication Communication Protocol which 
is based on the IPC Event Mechanism. This protocol will describe a 
standard set of messages defined by Apple. | 


The Operating System IPC layer should be appropriate for Network IPC, 
Comm Toolbox and others who are generally not driven by the standard. 
event manager. This low level mechanism provides services for creating 


queues. This inte rface...is...referred to as...the... Operating System IPC 


Mechanism. The IPC Event Mechanism is/built using the Operating System 


IPC Mechanism. - J eeveveeeeverseneeecereeeerserenr ed 


“es, 


cette enema cern meen e ee 
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Chapter 2 


The Event IPC Mechanism. 
“Messages are events; events are messages.” 
A New Event. 


The pre-7.0 Multifinder aware application® saw lower level 
events/messages null through app4Event. Each of the sixteen possible 
events has a multizpart.. Bo message: which could be. viewed in the 
EventRecord. These. lower level events/messages- could: be ‘masked,’ 

thereby allowing event/message. filtéring./ ea ne 

A new event, AHighLavelévent exists in “MultiFindér 7: 0. This event is 
“masked if app4Event.... ¢ masked’. § \ The EventRecord variant for 
kHighLevelEvent saapunas the Point member of the EventRecord 
structure’. See figure 2. ; i 


3. A yet to be defined bit in the SIZE resource indicates the application desire to handle High 
Level Events. | 

4. If the SIZE resource does not exist or the appropriate bit is not set in the SIZE resource, the 
application effectively masks kHighLevelEvent. 

5. Redefining EventRecord.where (Point) as EventRecord. what3 (Longint) implies that High 
Level Events don’t contain the mouse position at the time of the event. Currently, 
MultiFinder childDiedEvent don't contain a mouse position at the time of the event. This may 
cause trouble for application that case off of EventRecord. where before casing off of 
EventRecord.what. 


Pee ee oe a 
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struct EventRecord { struct EventRecord { 
short what; pe short what; 
long message; long what2; 
long when; long when; 
Point where; long what3; 
short modifiers; short modifiers; 


| if whatis kHighLevelEvent 


party developers who have registered an application signature are given 
the “class” of messages which have that signature as their what2 field’. 
Class can also be considered the signature of the ‘fella’ who decided what 
the message means. The contents of what2 must be registered with 
Developer Technical Services. 


The Rest of the Event/Message. 
Unlike other events, kHighLevelEvent has a number of fields which cannot 


be viewed in the EventRecord. The pieces of information which cannot be 
seen in the EventRecord are: 3 


6. This ‘two-tiered’ message type system avoids message “type collision.” 
7. Apple reserves all values of what2 that contain all lowercase letters. 


anne eee 
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¢« sender’s id 
- refcon® 
¢« data associated with message. 


After Receiving the event/message. 


After receiving a kHighLevelEvent in the main event loop, an application 
can “accept” or “ignore” the message. If an application wants to accept 
the event, it must do so before the next Get/WaitNextEvent. In accepting 
the event, the application is informed of the sender's id, refcon for the 
message and the message is copied into an application supplied buffer. If 
the application does not accept the event, the events is said to be ignored. 
The system makes note. of.accepting” or ignoring. the.event... rhe fact that a 
receiver accepted or. ane a event iS; javailenie to Pine sender of the 
event/message. re Bi as ean aasecuinarnelereisee Hi “ ae # 


anda set of flags describing’ ‘various delivery options. One of delivery 
option will cause a message/event '° to be posted” ‘to the sender when the 
target application accepts or ignores the message/event. Another option 
will cause the system to post the event/message in such a way that the 
message is delivered when the target application issues its next 


Get/WaitNextEvent. The data is copied into system buffers. 
Directory Services. 


Directory Services allow an application to see a list of IPC clients and 
appropriate information. The list associates a name with a long integer, a 
resource handle and a long integer describing characteristics of the name. 
The first long integer is used as a receiver's id or a sender’s id. There is 


8. refcon - reference constant. Generally 32-bits of information passed with a data structure. 

9. All fields in the EventRecord are specified by the user except when. The system fills in 
when with the time corresponding to the posting of the event. 

10. The message could look like ‘stdr’ ‘acpt’ <receiver's id><refcon><Accepted> or ‘stdr’ ‘nacp’ 
<receiver's id><refcon><Ignored>. 


ae Ash eet ae ele Be ee te 
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one directory entry for every MultiFinder 7.0 aware application. In 
addition the directory entry may contain a handle to a resource describing 
the High Level Events the directory entry is able to interpret. The second 
long integer describes if the name is: : 


* registered on the network 
¢ MultiFinder 7.0 friendly 


In addition, an application can ask the system for the Longint associated 
with a single name or ask the system for the single name associated with 
a LongInt. 


Selecting a ral ra dah 


Selecting a specific message/event is gone by” -spegttying a filter 
procedure. For each event on’ the-Event ‘Queue the Systém calls the filter 
procedure passing a _user.. parameters, the EventRécord, sender’s id, the 
refcon, a pointer to the.data and the length of data. ‘The system expects 
the filter procedure .to™return true or false. ¥ If false is returned the 
system calls the filter procedure’ with the next; Mitty: ion queue. If no more 
entries on the queue, “false” is ‘return. to the application. If true is return to 
the system by the filter’ “procediire, the event/itiéSsage is removed from 
the event queue and returned to the application. With this scheme, an 
application can scan the entire event queue or selectively remove any 
element. 


The Event IPC Mechanism Call Set 


Function WaitNextEvent (eventMask :INTEGER; VAR theEvent 
EventRecord; sleep : LongInt; mouseRgn : RgnHandle) : BOOLEAN; 


WaitNextEvent returns kHighLevelEvent in theEvent.what. theEvent.what2 
and theEvent.what3 identify which kHighLevelEvent. theEvent.modifiers is 
event dependent. theEvent.when, the event’s posting time, is the number 
of ticks since startup. 


An eventMask with app4Mask cleared masks kHighLevelEvent. 


a es a ee eS 
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Function AcceptHighLevelEvent (VAR senderID : Longint; VAR 
msgRefcon : LongIint; msgBuff : Pointer; VAR msgLen : INTEGER) 
OSErr; . 


AcceptHighLevelEvent is called when an application wants to accept the 
rest of the message. msgBuff must point to a buffer at least 512 bytes 
long. 


Function GetSpecificHighLevelEvent (filterProc : ProcPtr; param ; 
Longint; VAR theEvent : EventRecord; VAR senderID : LongInt; VAR 
msgRefcon : Longint; msgBuff : Pointer; VAR msgLen : INTEGER) 
BOOLEAN; 7 | 


GetSpecificHighLevelEvent is used. to filter events. The filterProc is 
c a | | e d b y t h e Ss y Ss t e m as’fott ewer r _pennataancceenntee nnn iaaiecnieaneeiacenaainnniey 


Function filterProc. (VAR param? Longint; theEvent 4 EventRecord; 
senderID : LongInt; msgRefé6ri™:..LongInt? msgBuff : Pointer; msgLen 
: INTEGER) :; BOOLEAN; . . , - f 


The filterProc is called for each element on fhe event queue until the 
“filterproc returns tfue of the end of the evert queue is reached. If the 
filterProc returns \true;..thé event is returned to the caller of 
Get SpecificHighLevelEvent..and-séanning of the-event queue stops. The 
caller of GetSpecificHighLevelEvent must specify a buffer of at least 
512 bytes. 


Function PostHighLevelEvent (theEvent : EventRecord, receiverID 
LongInt; msgRefcon : Longint; msgBuff : Pointer; msgLen ; INTEGER; 
postingOptions : LongInt) : OSErr; 


PostHighLevelEvent a kHighLevelEvent on the receiver's event queue. All 
fields in theEvent are filled in by the application except theEvent .when. 
The system fills theEvent.when with the ticks since startup when the 
event is posted. postingOptions are bit flags which indicate to the sys- 
tem various options when posting and delivering a message. 


Bit nReturnReceipt set to ‘1’ causes the system to post a message to the 
sender’s event queue when the message is delivered to the receiver's 
event queue. The message will indicate if the receiver accepted or 
ignored the event/message. 


Pace RS 8 Ea a a ee 
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Bit nAttnMsg set to ‘1’ causes the system to post the message as the next 
event presented to the receiver. 


All other bits are reserved for future functionality. There are no user 
serviceable parts inside. Breaking the seal voids the warranty. 


Function GetBlackBook (buff : Pointer; lengthOfBuff : INTEGER; VAR 
numberOfEntries : INTEGER; VAR numberOfEntriesRemaining : INTEGER) 
$ OSELL; 


GetBlackBook fetches a number of records. numberOfEntries contains the 
number of records that were return, in | buff. | 

Each record associates a name! ' with a Longint, a resource handle and a 
Longint describing characteristics “Of the: nafne. “The. Airst® ‘long integer is 
used as a receiver's id ora “senders id. “There is pine sirectory entry for 
every MultiFinder 7. 0 aware application and* an, entry for every 
CreateMsgQ?*. In addition the directory entry may contain a handle to a 
resource describing the. High Level Events the direétory entry is able to 
interpret. The second long. integer d describes i if ‘the name is: 


. eeced “onthe noENOTk 
¢ MultiFinder 7.0 friendly 
¢ various implementation dependent features. 


Function GetQidFromName (name : Str255; VAR Qid : LongInt) 
OSErr; 


Function GetNameFromQid (Qid : LongInt; VAR name : Stxr255) 
OSErr; 


11.name : Str255; 
12.See “Operating System IPC Mechanism.” 


TT 
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Chapter 3 


Operating System IPC Mechanism. 


The Operating System IPC Mechanism is for pieces of code which don't use 
the Event Manager. The interface is also available to MultiFinder 7.0 
aware applications. 


RTC 


is non-empty. The progratimer can.specity nill for’this’ procedure. This 
informs the system that~this, message queue -will “be polled by the 
programmer. The Message Queue id: return by the,system is a unique 


LongInt. 


The message queue Should be destroyed whén the: programmer no longer 
wants to receiver or send messages. i 


Finding memory at interrupt time or during certain of critical areas of the 
Mac’s environment is discouraged. Hence, two routines are provided to 
allocate and deallocate memory for messages. These routines provide 
coordinated access to the pool. In simple terms, they produce correct 
results when called from interrupt level and/or base level processing. 
When the creator of the message queue wishes to post a message, he 
request of message buffer from one of these routines. He should make no 
assumptions about the buffer other than its starting location and length. 
When a message is received by a process, it is the receiver responsibility 
to call the other message buffer routine to deallocate the message buffer, 
thereby permitting it reuse by a send operation. 


The Operating System IPC Mechanism Call Set 


13. This memory is set aside to ease the problems of getting memory for sending and receiving 
messages at Deferred Task Time. 


sp Bacgee mace pens ape he a eh 
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Function CreateMsgQ (msgQName : Str255; reserveMem : INTEGER; 


options : LongInt; receiveProc : ProcPtr; VAR Qid : LongInt) 
OSErT; 


Function DestroyMsgQ (Qid : Longint) : OSErr; 


Function GetMsgEventBuffer (Qid : LongInt; lengthInBytes : 
INTEGER; VAR buffPtr : Pointer) : OSErr; 


Function RelMsgEventBuffer (Qid : LongInt; buffPtr : Pointer) 
OSErr; 


Function GetNextMsg (receiverID : LongIint; VAR what2 : LongInt; 
VAR what3 : LongInt; VAR when : LongInt; VAR modifiers : INTEGER; 
VAR senderID : Longinty: VAR ¢ msgRefcon ; seongtee VAR buffPtr 

Po i nter ) : O SErr: 7 ‘ig dincaiateinncmeneucncandaizeees i prseennceennaneasnnnanniouinegmnccennecenccenenncesng 


Function PostMsg (séndex In... me Sena) postingOptiens | x } rongint: 
what2 : Longint; what3:: Longint ; modif¥ers : INTEGER; receiverID 
: Longint; msgRefcon sr ee qsgButt : cae aa ‘¢ OSErr; 


See ee Be a eS ee, 
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System Segmentation 


by Jim Straus and Joe Buczek 


One of the issues affecting all areas of System Software is that the System RAM requirement in- 
creases with each revision. The number of features we are planning to include in Big Bang will 
easily increase the size of the System to the point where applications, such as HyperCard, that 
previously worked in a 1 Mb system will no longer be usable. 


Before reading the following two proposals, Veg-a-matic and Monte Cristo, that deal with this 
problem, there are a number of not-strictly-software related assumptions! that you should consid- 
er 


¢ 1 Mb systems will continue to be sold by Apple well into FY90 and perhaps much 
longer. The solution we choose must cover 7.0, 8.0, ... 


¢ Networks of Macintoshes must be able to share LaserWriters and other sharable 
devices. 


¢ There is a fii 
System 7.0h 


¢ Users gentrally add.se¥eral Fopts, D/A’s afd Inits fo their systems that push up 
i 2 0 inimum. 


The following proposals describe ways to use segmentation to help reduce the System’s bur- 
geoning memory utilization. Both Jim Straus and myself hope these proposals will help us to 
make the best possible informed decision, if and when we must make a choice between them or 
even other alternatives’. Clearly, the impacts of both proposals are extensive. 


Both proposals present quite a bit of detail with regard to their respective implementations. There 
are a lot of subtle pluses and minuses, so you should read them both carefully and try to think 
about how segmentation would affect your particular area of System software. For those who are 
familiar with the details of the both proposals, the following table presents a cursory comparison: 


1. Excerpted from Charlie Oppenheimer’s memo of November 17, 1988 


2. Gifford outlined some of the alternatives at our last offsite. These included “do nothing”, 
“buy more memory”, “Veg-a-matic”, “Diet Apps”, and “bifurcation”. 
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Unloads active code Yes No 
Impact on Code Size/Speed Bigger/Slower Smaller/Faster 
Can Be Added to Existing Code Automatically Yes _ Not as easily 
Can Predetermine RAM Requirements Yes No 
Requires Additional System Segmentation Effort Yes Yes 


Finally, some of the less obvious points: 


1. 


Any segmentation scheme will introduce a significant performance penalty into the System 
that everyone must pay, even those who have plenty of memory. 


All existing patch code must be reworked to follow some segmentation scheme. This will 
require a significant one-time involvement from ail groups in System Software. 


In the future, all new features must be designed and implemented with segmentation in 
mind. System patches will become somewhat more complicated to write and maintain. 


paths will become les 
be expected that SQA 


Macsbug, etc. modifte 
Macintosh. 
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Veg-a-matic 


by Jim Straus 


ABSTRACT 


This section describes the implementation of the Veg-a-matic proposal. Veg-a-matic is a 
method of breaking code up into modules that will be loaded on demand and that may be moved 
or purged. Specifically, it does not require that the entire calling chain always be resident. Its 
purpose is to shrink the footprint of existing patches and also to allow Big Bang to fit into a 1 
meg Macintosh. 


INTRODUCTION 
Veg-a-matic is a mixture of a variety of methods designed to modularizing code. It is intended 


for both system patches and applications. For the purposes of this proposal, a module is a 
section of code that can be moved or purged any time it is not actively being executed, and when 


it is needed again it will be re eg-a-matic is similar to segmentation, in that code 
modules are loaded 6 y “d and that there ts jomp tabte to find the routines in the 
modules. The big difference is that therg only to be the currently qxecuting module in 


sould All be purged) and that 


ly 


to be modified if thang 

maintain an alternate stack of poink é 
KS needed. Whgn a modple is purged, the rgturn addresses that refer to the. 

pr will occyr whenjthe address is used. The Address 


When someone wants to calraToutine in a module, they make the call through a jump table. The | 
jump table will either jump directly to the routine in the module if the module is loaded or load 
the module (with a trap) and then jump to the routine after the module is loaded. Because we 

will need to potentially find every jump table, the system maintains a dictionary of jump tables. 
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Veg-a-matic Desig n 


Lets start by looking at the data structures that Veg-a-matic uses. The first structure is the Jump 
Table. It is used to find the entry points in a module and to find modules in general. It is very 
similar to the Jump Table used by the Segment Manager. The only real difference is that the 
module number has the high bit set and that in the unloaded state the module entries have 
_LoadModule instead of _LoadSegment as the trap. In fact, for applications, modules and 
segments can be mixed into the same Jump Table. This would allow an application to be made 
entirely of modules if desired and still allow the launch process work unchanged. Also, there 
may be multiple Jump Tables in use at any given time. Presumably there is one per application 
and probably a few for the System. In particular, there is probably one per Extension as defined 


by the Extension Manager. ! 


The Jump Table Not used by System Jump Table 

a 

_LoadModyse l 

- 
One consequence of havingYyump taDf€s is that p ked down. This is 
because we will have to modifythe.addresses in the jump ta aenever a module is moved or 
purged. 
The Jump Table Size of table 


Dictionary 
Entry for remembered Jump Table 


Entry is free 


0000000¢ Fa 
Ptr to Jump Table 
File RefNum 


The Jump Table Dictionary is used to find Jump Tables when a module needs to be purged. It 
contains a pointer to the Jump Table and the file RefNum for the file containing the Jump Table 
and its modules. This implies that there must be at least one Jump Table per file containing 
modules. However, a file could contain more than one Jump Table (for example: the System). 
The Jump Tables are added to the Dictionary by the trap _InitModule and removed by 
_ExitModule. The Dictionary is searched for free entries (identified by 00000000) when a Jump 
Table needs to be added. If none are available, the Dictionary is grown by some preset amount. 
There is only one Jump Table Dictionary in the entire machine. It is shared by the system and 


eh Da a 2 a a a hr a a eee 
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applications. 


1 The Extension Manager handles "optional" traps. That is the traps may not always be 
available, but are requested on an application to application basis. See Brian McGhie for details. 


The Module Table 
in Table 

File RefNum: ResID 

File RefNum: ResID 

0000000¢ 

0000000( 


Ptr to Jump Table 
File RefNum: ResID 


The Module Table is a dynamic table used to identify unloaded modules. It is used to find the 
modules again when we encounter an unloaded module's "return address" on the stack. An entry 
contains a pointer to the Jump Table that contains references to the module as well as the File 
RefNum and ResID (which is the mode ee without the high bit Set) needed to reload the 


Size of table 


Entry for remembered Module 


Entry is free 


A Module 


IF Fset Sree the firstNnroutine' 
fezy fon ty Rart of mp Tab Ses ‘abl 
atc € jum € 

ne of sly sia | P jump 


fvonte: a 


ot 


JSR AltPush 
BSR Foo 
ADDQ.L #4,AltStack 


Patch Table 
Offsets to JSRs and the 
module and entry to call 


Now that we know all about how to find the modules and the code within them, lets look at the 
module itself. It starts out with a header that is used to find the actual entries in the jump table 
(to be patched) and the offset needed to find the patch table. The patch table contains entries for 
places that need to be patched within the module. The patchings take place when the module is 
loaded in from disk. The first thing that needs to be done when loading a module is to point the 
jump table entries at the correct places within the module. This is done in the same manner as 
for segments. Then the module itself needs to be fixed up so calls from the module point to the 
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correct places in the jump table. Each entry in the patch table specifies the offset to JSRs that 
want to call other modules and the module number and entry they want to call. This implies that 
modules can only directly call other modules that are refered to in the same jump table. After 
the header there is the actual code of the module. We'll discuss the requirements of the code in 
the module in a moment. 


The last data structure is the alternate stack. It is used to find return addresses on the real stack 
that refer to locations in a module. The reason we need to find these return addresses is so we 
can modify them when a module is moved or purged. 


The Alternate Stack 
Alternate Stack Real Stack 
ee td > ae a The module number 
Bares fe) (offset in module table) 
eel NS A we need to return to. 
return address 


area ace 

Pointer to address 

return address ee a 
address 


~- 


table(s) for the heap zone needing the spgée (by logking through the jymp table dictionary). 
Once the correct jump table 
table by some process (perhaps“s king-thfough the alterrate-stack to the return stack and 
finding a module that isn't in the calling chain). Once the desired module is selected, the pointer 
to its jump table, its file RefNum and ResID (which is the module number without the high bit 
set) are stored into the module table. Then the module's entries in the jump table are fixed up to 
reload the module. Next we need to fix up the return addresses on the stack, so the alternate 
stack is used to find and examine each return address on the real stack. Any that fall within the 
module that we are about to purge are changed so that the high word contains the number of the 
module table entry for the module that we are about to purge (that is, the offset from the start of 
the module table). The low word contains the offset from the beginning of the module to the 
point specified by the return address with the lowest bit set (that is: the return address minus the 
start of the module plus one). The reason for the lowest bit being set is so that when some 
routine tries to return to the purged module an Address Error trap will occur. Then the Address 
Error handler will reload the module, fix up the jump table, module table and the return stack 
and then resume at the fixed up address. It should be noted that when a (system) module is 
purged or reloaded, all the alternate stacks will need to be examined and fixed up. 
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Summary of the Infrastructure or... 
Who Knows About Whom 


Global 


Jump Table Dictiona) 
ee ee ea 


System Heap 
Jump Tabl« 
Jump Table 


( ump Tabli 
a 


‘& Alternate Stac 
Real Stac! 


When modulej ref eto. 
the address} is unloaded 


Module Tabl 


Global System Cow 


AltStack,Al 
SP, -(Al) 


#4, (Al) 
Al, AltStack 
(SP)+,Al 


Because Multifinder is switching stacks around, we will need an alternate stack per real stack. 
For this reason, Multifinder should create the alternate stack when it creates a real stack for an 
application and it should take care of switching alternate stacks when it switches the real stacks. 


A final item, which isn't really a data structure is the global system code every module needs to 
access. This is AltPush, which saves the stack pointer on the alternate stack. This needs to have 
a low memory area or pointer assigned to it so that every module can know where to find it. If 
we decide that this is too distasteful, a trap could be used. The big problem with a trap 1s the 
time overhead needed to make the call. 


Now that we've seen the basic data structures, lets look at the requirements for the code in a 
module. First of all, whenever a jump table that contains modules is loaded, the jump table 
needs to be registered with the Module Manager so the manager may register the jump table in 
the jump table dictionary. This is accomplished by calling _InitModule(MyJmpTable: 
PtrfoJmpTable; ResourceFile: RefNum). This call installs the pointer to the jump table into the 
Jump Table Dictionary along with the file reference number. Whenever a Jump Table is to be 
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disposed of (for instance, as when an application exits to the shell), it should call _ExitModule( 
MyJmpTable: PtrToJmpTable) with the same jump table. This removes the jump table from the 
dictionary. It would be nice if MultiFinder would make this call automatically on ExitToShell. 
Or we could patch CloseResFile to check for a Jump Table (CODE 0) resource and if it existed, 
to make the ExitModule call. Forgetting to make the call will be probably be deadly unless the 
PurgeProc checks to make sure that the jump table is valid before trying to purge modules from 
it. 


Now lets see how a call from inside a module works. When a module routine wants to call a 
subroutine and that subroutine (or any of its descendants) is outside the module or might cause 
the memory to move then we need to be able to find the caller's return address on the stack so we 
may change it if necessary. To do this we call a subroutine called AltPush that will record the 
current stack pointer on the alternate stack. We then procede with the call. After the call 
returns, the item on the top of the alternate stack is not needed, so we just drop it from the 
alternate stack. 


The code for a call looks like: 


JSR AltPush 3; save the current position of the stack on altstack 
BSR Foo ; make the call 
ADDO.L #4,AltStack fust throw away the pointer from the altstack 


AltPush MOVE.L Al,- (SPP 
MOVE.L AltStac 
MOVE.L SP, - (Alf 
ADDO.L #4, (Al) 
MOVE .L Al, AltStack 
MOVE .L (SP) +,Al1 
RTS 


form of AltPush that goes f& 

FastAltPush 
MOVE.L AltStack,Al 
MOVE.L SP, - (Al) 
MOVE.L Al, AltStack 
RTS 


And on a 68020 or higher it might even be optimized further. Here is a picture of what the call 
looks like and what is stored on the alternate stack and the real stack. 
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AltStack 


Intramodule call. 
When we are in Foo's module. 


Offset into Jump Table Alternate Stack 


Number of entries in Jump Tabl: 


Offset to patch tab] 
Number of patch entris return address 


BSR Foo 


Foo's retur! 
ADDQ.L #4,AltStack 


address 


Foo 


RTS 
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Making a call to another module is basically the same. The difference is finding the other 
module. To do this we make a call through the Jump Table. 


Jump Table 


fF Froomtodute: om re | 
AltStack 


Alternate Stack 


Pointer to 
return address 


Real Stack 


Intermodule call. 
When we are in Foo. 


Offset into Jump Table 
Number of entries in Jump Tak 
Offset to patch tab: 

Number of patch entric 


Offset into Jump Table ie 
Number of entries in Jump Tabl | 


Offset to patch tab: pieces) 


Number of patch entris 


JSR AltPush 
JSR Foo 
ADDO.L #4,AltStack 


nf 


It should be noted that only rom modples need this overheAd of uging the alternate stack. 
If we have static patches, titey can\make calls direcfly to the jugnp tabl¢ just as they would to 
normally static code. Alsolif a m@dule galls localfoutines thgt will n¢ver move or purge 
memory nor will any of its descendamS then it gah just makefimple HSR calls. However, it 
would take more extensive compHersupporeto make this optimization automatic. Finally, 
GetTrapAddress just returns a pointer to the jump table entry. | 
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Things that need to be done:. 


PurgeProc The purgeproc needs to define some sort of priority for purging 
modules from a heap. This might include a built in priority (eg. least recently used) 
as well as programmer hints (eg. I'm going to need this soon). It needs to add 
information to the Module Table and fix up the return stacks and the jump tables. 


Address Error Handler The exception handler needs to reload the module into 
the correct heap and fix up the jump table and return stack for the reloaded module. 
It should work closely with the purgeproc. 


MPW Compiler modifications The compilers need to be modified to create 
module entries and when creating module entries to add the extra code around each 
call (including trap) they make. Also, they need to not include (constant) data in the 
modules, but put the data into a static segment. 


MPW Assembler modifications The assembler needs some macros to generate 
the correct calling code for modules and directives to generate module entries for 
the linker. | 


Module Memory management Where ever the system modules reside (Temp 
Memory, our own Heapzone), the zone they are in needs to always have at least 
enough room for the largest module possible as well be able to shrink and grow as 
applications are launched and exited. 


Temp Memory rules A set of rules and protocols are needed for adding things to 
temp memory and how they will be requested to be removed. 
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Monte Cristo: 
Dynamic Segmentation with Use Counts 


by Joe Buczek 
Part I 


This proposal describes a possible solution to our increasing memory problem in 1 megabyte 
Macintosh systems. The goals of this proposal are: 


1. Provide an automatic way for code to be purged when not needed. 


2. Minimize changes to the programming model and changes to existing development 
tools. 


3. Enable the System, Finder, and Hypercard to coexist in a 1 Mb Macintosh. 


Essentially, Monte Cristd presents a Classice mainfyame 9 er segmentation overlay 
scheme by maintaining ¢ e count” for each codq seg 2 t is maintained by a 
combination of a modifidatiop Arguage co y ynt Loader, Jump Table 
entries, and the Memory Manager 

Jump Table entries will odified s\ich that they increm segment’s use count upon 
each entry to a routine i ditionally, returns frfm rougines in a segment will decre- 


cannot be moved or purged. 


Monte Cristo requires that titwhele-eatfing chain of cod in memory for the duration of 
the chain’s execution. In order to minimize the memory resident footprint, analysis of code using 
this segmentation method will need to be performed to minimize the set of segments that must be 
loaded at any given time. This will probably require restructuring of the Finder, PrintShop, etc. 


The total amount of memory available for loading segments will determine the depth of analysis 
required: the less memory available the more analysis required. Additionally, the less memory 
available the smaller the average segment size is likely to be. If functions are grouped into small 
enough partitionings, “out of memory” conditions can be avoided because segments that are not , 
active can be purged to create space for those that are needed. 


In addition to dynamic segmentation, a technique for reducing the size of Jump Tables called 
“Entrypoint Multiplexing” (described in Part II) is proposed. 


Apple Confidential | Page 1 


January 10, 1989 Monte Cristo 


li 
All Set for addressing the 1 Mb Sears Soblen thus far have required modifications to 
the routine calling and return sequences. Monte Cristo also requires such changes, but only with 
respect to maintaining a module’s use count. When a routine is called, its module’s use count is 
incremented by code residing in the Jump Table Entry. When the routine returns, its module’s 
use count is decremented by code residing in each routine at its return point. 


In addition to dynamic segmentation via use counts, Monte Cristo also proposes a method of re- 
ducing the number of Jump Table Entries called “Entrypoint Multiplexing”. Entrypoint 
Multiplexing also requires a change to the format of Jump Table Entries. 


While the following sections describe the method of maintaining module use counts, details of 
the changes to the Jump Table Entries needed for Entrypoint Multiplexing are described in Part 
II of this document. 


Use Count Incrementation 
The use count for a segment is incremented each time a routine in the segment is entered via the 
Jump Table Entry. The segment use count is incremented by an additional instruction in the 
Jump Table Entry, 


for use as the segme Would provide hemos fut and efficient storage since the 
address of the use count cell would be at a compile- -time constant offset from PC. Hence only an 
LEA and a SUBQ would be needed for decrementing the segment use count. 
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Entrypoint Multiplexing 
What Is It And How Might It Help Us? 


Part II 


In considering the various segmentation proposals for dealing with the [Mb Macintosh memory 
problem, Jump Table entry size has proven to be one of several limiting factors. Some way of re- 
ducing the number and or size of Jump Table Entries would be very helpful in order to reduce 
the non-relocatable memory footprint, and to relieve the current 4096 entrypoint limitation (see 
below). 


One way of reducing the number of Jump Table Entries is to use a single external entrypoint 
(Jump Table Entry) to access multiple routines. 


This would work by assigm a module. To call a 
routine, the caller would : would then branch 
to the module’s multiplexed ¢ : ¢ routine selector to 


The advantages of Entrypoint Multiplexing: 


1. It reduces non-relocatable memory footprint by reducing the number of Jump Table 
Entries required to just one per code segment. 


2. It removes the current 4096 entrypoint Jump Table limitation imposed by the Segment 
Loader. The current Segment Loader implementation of Jump Tables limits the number 
of intermodule entrypoints to 4096 due to the fact that the Jump Table resides in a re- 
source (CODE ‘0’, limited to 32k bytes), and each entry takes 8 bytes. Hence the number 


of entrypoints is: 
32k bytes (Resource Manager limit) 4096 Jump 
8 bytes per Jump Table Entry Table Entries 


I believe this limitation has already been encountered by application code (written using 
MacApp). I don’t know whether or not a limitation of 4096 entrypoints is a problem for 
the System. 


The advantages described above are had at the cost of performance because each routine call 
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must decode a routine selector into an effective address for the desired routine. 


in iplexi 2 
Using ResEdit, several common applications were examined to collect some statistics about po- 
tential savings using a entrypoint multiplexing approach in the Jump Table. The table below 
shows the possible savings that would be realized if these applications were to employ the entry- 
point multiplexing technique described above: 


CODE 0 Size Jump Table #of Savings 
FullWrite Professional 23080 2885 117 21208 
Expert 0.2 16648 2081 28 16200 
AppleLink 4.0 2040 1848 
Finder 3304 3144 
HyperCard 8600 8280 
MacDraw II 4752 4240 
MacPaint 2.0 1464 
MacProie 2264 
MacT@rminal 2432 
Mac Wri 2440 
MPW 8320 
Multi 1696 
Savings 
in BYTES 
Avera 6647 
Averfige! w/o\FullWrite 5144 
Average* w/ofFullWrfe 94137 3904 


Generally, the more segments the greater the savings. While this does not seem to apply to most 
applications now, applications could conceivably be dissected into smaller pieces in order to 
achieve a smaller footprint to implement a strategy such as Diet Apps. 


1. FullWrite had 6 times more than the average number of segments, so it is removed in these averages as the “odd 
one out”. 


2. This was the handiest, smallest, MacAPP application I could find. I’m not sure whether it is indicative of object 
oriented applications in general with respect to the size of its Jump Table, so it is excluded here for illustration 
purposes. 
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Implementation 
How can we do this and what aces it cost? 


Part Ill 


To make Entrypoint Multiplexing as efficient as possible, a JSR cannot be used to call a routine 
through a multiplexed entrypoint. This is because the order of the routine selector and the caller’s 
return address on the stack would be in a non-optimal order. To avoid having to shuffle the stack 
the following calling sequence would be used: 


<push calling args> 
PEA @1 


@l: 


patching to the desired ra 
the stack would look like thi 


P cepytn aaarefs 


argument #2 


S6tca. 


The Jump Table is the logical place to do some of the work needed for maintaining the segment 
use count since entry to external routines is through a Jump Table Entry. This section describes 
the changes needed in the Jump Table and Segment formats to implement Monte Cristo. 


New Jump Table Code 

The following code would reside in a module’s Multiplexed Jump Table Entry. Basically, it up- 
dates the module’s use count, calculates the effective address of the routine being called using 
the routine selector shown in the stack description above, then branches to the desired routine. 
The code to do this would look like this: 


MOVE .L #<segBase>,AQ ; Point to segment base 


ADDQ.W.. #1, (AQ) ; Increment segment use count 
ADD .W (SP) +,A0 ; Calc target routine’s address 
JMP (AQ) CO. LO: -2 bess 
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As in the current Segment Loader scheme, the value of <segBase> above would be maintained 
by the Segment Loader when loading or unloading the segment. Because the Jump Table is mul- 
tiplexed, there is only one Jump Table Entry for the entire module. In contrast, the current 
Segment Loader scheme maintains the equivalent of <segBase> for every entrypoint. 


The use of register AO is assumed in the code above given that the target routine is a high-level 
language routine. Routines that pass arguments in AO could not use this mechanism. 


lin ni 
The diagram below shows an alternative format for Jump Table Entries that supports Monte 
Cristo. There would be one Multiplexed Jump Table Entry for each module. Routines would be 


invoked by pushing all calling arguments, pushing the return address (via PEA), pushing a rou- 
tine selector, then executing a JMP to the module’s Multiplexed Jump Table Entry. . 


The whole calling mechanism looks like this: 


Calling sequence: 


<push args> —- 


<segBase> (PC) ,Al 
#1, (Al) 

(SP) +,Al 
#<argSize>, SP 
{Al) 


Multiplexed Jump 
Table Entry 


Monte Cristo 
Dynamic Segment 
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: r 
The calling sequence given below includes setup done by the caller as well as code in the 
Multiplexed Jump Table Entry. The sequence below assumes that AO can be freely used to han- 
dle incrementing the segment use count. 


First, let’s look at the code that would be executed to effect a call: 


<push arguments> 


PEA @1 ; Push return address {16(2/2) } 
MOVE .W #<select>,-(SP) ; Push routine selector {12 (2/1) } 
JMP <segEntry> ; Go to routine’s module {10(2/0) } 


Ql: 


The JMP to <segEntry> above would take us to the Multiplexed Jump Table Entry, where the 
following code would execute: 


MOVE .L #<segBase>, A0 ; Point to segment base {12 (3/0) } 
ADDQ.W #1, (AQ) ; Increment segment use count {8(1/1) } 
ADD.W (SP) +,A0 ; Cale target routine’s addr {12(2/0)} 
JMP xe aa {8 (2/0) } 


The cost of a call setup in bytes, 38 instruc- 


The total calling executi Bec. Segment Loader scheme in- 
curs an overhead of 3.37! for ai! sec per iftersegment call. Return costs 
are figured below. 


A Pascal-style return sequence typically returns through register Al after removing calling argu- 
ments from the stack. The sequence below assumes that Al can be freely used to handle decre- 
menting the segment use count: 


myReturn: 
LEA segBase (PC) ,Al ; seg use count ptr {4,8(2/0) } 
SUBQ .W #1, (Al) ; decrement it {2,8(1/1) } 
MOVE .L (SP),Al ; get return addr 
ADDQ #argSize,SP ; discard args 
JMP (Al) ; ...return 


The additional overhead (indicated by boldface) for a Pascal-style return sequence is 6 instruction 
bytes, 16 instruction clock cycles, and 4 memory reference cycles, or 2.5 Sec. 


3. For the purposes of this proposal, all instruction and memory timing discussed below assume typical 1 Mb 
Macintosh characteristics: 68000 processor, an 8MHz clock, and zero wait-state memory. 
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r 
The total additional overhead for entry and exit of a Pascal-style routine using Monte Cristo 
would be: 


Per Call 12 pSec 
Per Return 2.5 uSec 
Total per routine 14.5 Sec 


-Segm li 
Intra-segment calls can be done by simply using BSR instructions without incurring any of the 
overhead described in the previous sections. Only routines that are external need to update the 
segment use counts. | 


It should be noted that if a routine is externally callable and needs to be called from within the 

segment it resides in, the Multiplexed Jump Table calling sequence must be used to insure that 

the segment use count is properly updated. This is true since code to decrement the segment use 
Ne TOUUNDS : 


count is embedded_ip sequ 
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Conclusions 


Part IV 


The techniques described in this document are certainly not ideal in terms of a programming 
models or performance. Ideally, we would instruct users to purchase additional memory and/or 
upgrade their equipment to be able to support virtual memory. However, for the purposes of this 
proposal, these alternatives are not being considered as the solution because no concrete deci- 
sions have been made yet as to what we will do and when. Also, since products currently under 
development will continue to exhibit the “I Mb problem”, so we must do something. 


The following are observations that have presented themselves to us along the way. While not 
conclusions, they are certainly relevant and 


ing and swapping cade fro disks howl yeh of a‘ i odicti ty tool” are we really 
selling? 

¢ The original 128K Magfarned a Nputation of being a “to@ster” Avith respect to the amount 
of disk swapping the.user was asked to pesform. We s avoid doing this to our users 


again, even at the c elli gm to buy more RAMI. 


With respect to Monte Cristo, if code is properly segmented, a dynamic segmentation technique 
could afford the greatest performance with the least impact to programming model and develop- 
ment tools. 
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v M ri 
The following is a list of the advantages and disadvantages of Monte Cristo: 


Advantages 

1. Doesn’t swap live code. Reduces thrashing. 

2. Minimizes performance impact. Only needed for intersegment calls. » 

3. No “AltStack” or stack crawl needed. 

4. Entrypoint multiplexing saves Jump Table space. Removes Segment Loader’s 4096 
entrypoint limitation. Makes Jump Table use by System code more manageable. 


Disadvantages 

1. Can be difficult to establish the minimum footprint. You can still run out of memory 
if the worst case segmentation is not thoroughly understood. 

2. Requires significant modification to development tools, including compilers, linker, 
and assembler. 

3. Would require establishing a Jump Table mechanism for the System. 

4. Would require thorough understanding of code segmentation needs by each develop- 
er and group. 


Requirements fo 
The following is ¢ 
order to implemenf the Monte Cristo dynamic/segme 


4. Create a patc ory Manager that trie ach for and purge unused segments 
upon encountering an “out of memory” condition before actually returning memFullErr to the 
caller. | 

5. Devise aJump Table management scheme for System code. 


6. Review segmentation and partitioning requirements of existing code (the effort required to re- 
view code partitioning requirements and make necessary changes could be substantial). 
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The Macintosh Desktop Manager Interface 


by Patrick W. Dirks 
June 229d, 1988. 


NOTE: This document is a draft of a design in progress, and may 
change without notice in the near future. It is not meant to 
define the final interface to the proposed facility. 


1. Introduction. 


The Finder presents Macintosh user with a unique user interface 
centered around the use of icons to represent objects on a disk volume. To 
present this interface to:the userthe Finder makés Usé ofa number of data 
structures separate from the File System's volume catalog, all of which are 
maintained as resources of; vaneus wees in an invisible resource file ‘called 
‘Desktop’. SS % of | 


The Desktop file is. ‘ caifenily Used to Perform miles éeparzte functions: 

1. To associate. Gocurnents and applications with pariicular icons 
through its ‘bundle’ mechanism, BS well as storing, the actual icon 
bitmaps, , se 


2. To locate the corresponding application when a user opens a 
document, and 


3. To store the text of comments associated with files and folders as 
part of the information displayed by ‘Get Info’. 


The management of icons centers around the concept of a bundle, stored 
as a resource of type BNDL in an application's resource fork. The BNDL 
resource, which is identified with a particular FileCreator type can, among other 
things, refer to a number of FREF resources, which can in turn indicate that a 
file of a particular type should be displayed using a particular icon. Together, 
BNDLs and FREFs can be used to determine the icon to be displayed for a 
given file from the Creator and Type information stored as part of its Finder Info 
in the catalog. 


In addition, the Desktop file is used on HFS volumes to hold a list of 
applications stored in subfolders on the volume. The desktop contains an 
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APPL resource which is used by the finder to find an application to launch 
when a document is selected, given the document's FileCreator information. 
The APPL resource basically maps a particular Creator type to a list of 
applications that can open documents of the specified type. 


Finally, the Desktop file is used as a repository for the text of comments 
associated with files and folders on the volume. Comments are retrieved when 
the user selects 'Get Info' for a file or folder, at which time the comment text 
can also be changed. 


The use of the current Desktop file structure in a Network Environment 
(i.e. on File Server volumes) has proven unsatisfactory: resource files, such as 
the Finder's Desktop file, are ill-suited for sharing among multiple users on a 
single File Server. In addition, the use of resource-file based Desktops is 
unsatisfactory for large yelumes- due toa gombination: oftimitations-on the 
Resource Manager itself and eieleney of the resource structure ny hundreds 
or even thousands of entries ae a og 


A new mechanism for the. storage ahd manipulation oft this, = Deskin 


Manager calls. 
The Desktop file is sania cad by two new files: . 
¢ AB*-Tree file containing the information required to link files on the 
volume with their icons and comments, as well as to suitable 
applications to open a document, and 

¢ A data file containing the actual icon images to be displayed. 

The reason for their separation is related to the size of the icon images to 
be stored: they are too large to be kept in the B*-Tree. Since icons are never 
removed from the Desktop file in the current implementations, it is 
straightforward to allocate space for the icons in another file, and retaina 
pointer to the storage in the B*-Tree. 


This note concentrates on the interface to the Desktop Manager; it is not 
intended as a detailed discussion of the Desktop Manager's implementation. 


2. Call Interface 
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The Desktop Manager interface includes three groups of calls: 


1. Icon calls (Addicon, Geticon, and Geticoninfo), 

2. APPL calls (AddAPPL, DeleteAPPL, and GetAPPL), 

3. Comment calls (AddComment, DeleteComment, and 
GetComment). 


| Each call can be mapped into a corresponding AFP command. The 
semantics of the AFP calls parallel the semantics of the interface routines; for 
File Server volumes, little more than packing of the procedure arguments and 
unpacking of the results is required. | 


In the descriptions of the individual calls in the following sections, the 
data type ResType refers-to-the- 4-byté signatures: that-are-part-ef-every file's 
Finder Information. Each file is assigned a 'File/Type' meant tobe 4 
representative of the nature- ofthe-conterits of the file (PNTG; TEXT ‘etc.) and 

a 'File Creator’, which is a unique: signature indieating the apptication which 
created the file (such as MPNT. -MACA, eg) y : 


2.1 Desktop Manager Access 

Desktop Manager adie, can bé made. ee Paséal, (or. c) and from 
assembly language. The assembly langtiage intertace is a ‘parameter block 
based interface, quite similat'to'the File System's. Déstktop manager calls can 
be made synchronously or asynchronously. The Pascall calls are simply "glue 
routines" that set up a parameter block on the stack and make a synchronous 
_HFSDispatch ($A260) call with DO set to the appropriate selector for the call. 


The assembly language interface to the Desktop Manager uses the 
following basic parameter block layout: 


General DTMgr Parameter Block a 


O($0): : 
B(510): A(S16): G(SIA): 
se i gato a asnuh ioRefNum lolndex 

32($20): 40($28): 

ioBuffer “ Reaceunt ioActCount 


Before any Desktop calls can be made, the user must make an OpenDT 


ioCompletic 


ioTaginfo 
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call, as follows: 


Function OpenDT( \VRefNum: Integer: 
Var DTRefNum: Integer): OSErr; 


This call cannot be made from an interrupt. The file RefNum returned for the 
Desktop Database must be used on future calls to indicate the Desktop 
Database being referred to. If an error occurred on the call, the refNum 
returned will be zero. If the Desktop Database was already open, no error will 
be returned to the caller, and the ioRefNum field will contain the same 
DTRefNum returned on the original OpenDT call. 


When all Desktop operations have been completed, the user should 
make a CloseDT call (which takes a single argument, the DTRefNum) and 
returns an OSErr. This wittfree-alt'resources allocated-as ‘part of the, OpenDT 

call. CloseDT cannot be called from an interrupt. This call is generally made — 
only by the Finder or at System ‘Shutdowh time; CloseDT will inimediately 
close all Desktop files and free-altin-memory date’ structures: " Untess you're 
sure you! re the first and ony user. of the pestiop Database, it’ S. best to leave it 


lau nches. oot, 


In the assembly ey intertace, on an OpenDT cdl I (which is made 
as an __HFSDispatch $Ax60 call ‘with Do=$20), the ioV RefNum/ioNamePtr 
fields are used to indicate thé’voturtie whose Desktop Database is to be 
opened. If the call is successful (ioResult=NoErr), the ioRefNum field will 
contain the DTRefNum. This call must be made synchronously and cannot be 
made from an interrupt because it allocates and deallocates some memory in 
the system heap. 


The CloseDT call (_HFSDispatch with DO=$21) takes is DTRefNum 
argument in the ioRefNum field and returns a result in ioResult. Like OpenDT, 
this call must be made synchronously and cannot be made from an interrupt. 


All other calls can be made synchronously as well as asynchronously. 
2.2 Icon Related Calls 
Function Addicon( DTRefNum: Integer; 
| FileCreator, FileType: ResType; 
IconType: Byte; 


IconTag: Longint; 
BitmapSize: Integer; 
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Bitmap: Ptr): OSErr; 


Addicon adds a new icon bitmap to the Desktop database. The FileType 
and FileCreator arguments (4 bytes each) specify the set of files this icon is 
associated with, while the IconType argument may indicate a specific kind of 
icon (such as color vs. black and white). Note that for a given 
 FileCreator/FileType, there may be a number of icons available, each with a 
different lconType. The IconTag argument indicates a Longint value to be 
associated with the icon which will be returned along with the icon bitmap when 
itis retrieved. This could be used as a timestamp, for instance, to associate 
the creation date of the application with the icons it exports. Finally, the Size 
and Bitmap arguments provide the actual bitmap in questions. Note that the 
transmission protocols impose a limit of roughly 4.5Kb on the size of individual 
icons. mee 


If an icon of the specified ‘cont ype: jalready exists for the indicated 
FileCreator and FileType, Addtcon will replace’ the bitmap storéd with the new 
Bitmap. An error will bé returned” ifthe. size of the’ new bitmap Is different from 
the size of the old bitmap. ot _ ; f 


Function Geticon( DiRetNum: nteger: 
FileCreator: ResType: 
‘FileType: ResType; 
lconType: Byte. 
Var IconTag: Long; 
Var ActualType: Byte; 
Var Length: Integer; 
BitMap: Ptr): OSErr; 


Geticon retrieves the bitmap for a given icon, given its FileCreator, 
FileType and IconType. If no icon of type IconType is available, an 
ltemNotFound error is returned. On return, the ActualType argument is filled in 
with the type of the icon returned [this is really there only for historical reasons - 
should it be removed7 The IconTag argument is filled in on return with the tag 
associated with the icon when it was added to the Desktop database. The 
length argument used on input to indicate the size of the buffer pointed to by 
the BitMap pointer. When the call is completed it is overwritten with the actual 
size of the bitmap returned. 


Function Geticoninfo( DTRefNum: Integer; 
_ FileCreator: ResType; 
Iconindex: Integer; 
Var IconTag: Longint; 
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Var FileType: ResType; 
Var IconType: Byte; 
Var. Size: Integer): OSErr; 


GeticonInfo retrieves a description of an icon, given its FileCreator type 
and a numerical index. It can be used to determine the set of icons associated 
with a given application without knowing the FileTypes in advance. Successive 

calls with increasing values of IconIindex will return information on all icons 
associated with a given Creator type. 


Assembly language Addicon, Getlcon, and GeticoniInfo calls use the 
following parameter block fields in addition to the basic fields shown earlier: 


Addlcon, Getlicon, and Geticoninfo: 


Ba ($34): — § 156($3 38): Rael 
Pipe ieee: mat ; _ FileType | : 


a iA = Must be zero™ 


Addicon is made’ as ani _HFSDispatch trap with’ DO= $20, Getlcon is 
made with DO=$23, and Getleaninfo i is ‘mate with D0 set to fas 


Function AddAPPL( DTRefNum: Integer; 
FileCreator: ResType; 
DirlD: Longint; 
. CName: String[31]; 
APPLTag: Longint): OSErr; 


AddAPPL adds an entry for the application specified by the DirlD/CName 
under the indicated ResType. The APPLTag argument is an additional Longint 
stored with the mapping information. The application in question must exist 
when the call is made. 


There may be more than one application with same FileCreator ResType, 
although the DirlD/CName should uniquely identify the file. The Tag 
information might be used to decide among many possible applications which 
one to launch for a particular document (if the tag of the creator were stored in 
the Finder information of the document, for instance). The application's 
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creation date might be a useful tag. 


Function RemoveAPPL ( .DTRefNum: Integer; 
FileCreator: ResType; 
DirlD: Longint; 
CName: String[31]): OSErr; 


RemoveAPPL removes the mapping information for a given application 
indicated by its DiriD/CName. The file need not exist any more when the call is 
made. Note that while the FileCreator type must be specified to locate the 
entry, the application tag is not required to remove an application entry. 


It is the responsibility of the Finder (or whoever is creating or deleting 
applications) to add and remove APPL,entries for applications which are 
copied to the volume or:deteted; respectively. For-entries‘whichare-moved or 
renamed, the Finder should remove the entry before the operation arid add a 
new entry with the updated; information: ‘after the opération has.beer’ ‘completed 
successfully. This will avoid Jnconsistengies inthe ey Database. 


Function GetAPPL ( _DTRetNum:; Integer; 
_FileCreator: ResType; 
/ Index: Integer; 
,, Var APPLTag: Longint; 
“Var DirlD: Longin fe 
CNaitiesStringPtr): OSErr; 


GetAPPL looks up an application given its Creator ResType. The index 
argument is used to enumerate all application mappings stored. Indices 1 
through n will retrieve the 18 through n*'" application mapping stored which are 
accessible by the caller (i.e. on an AppleShare File Server, to which the user 
has Search and Read access). Unless the caller wishes to implement a 
special selection algorithm over all available applications, a single call to get 
the first mapping should suffice to find an application which can be launched to 
open the selected document. 


Assembly language AddAPPL, RmvAPPL, and GetAPPL calls use the 
following parameter block fields in addition to the basic fields shown earlier: 


AddAPPL, RemoveAPPL, and GetAPPL: 
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AddAPPL is made as an __HFSDispatch trap with D0=$25, RmvAPPL is 
made with D0=$26, and GetAPPL is made with DO set to $27. 


2.4 File Comment Related Calls 


Procedure AddComment( DTRefNum: Integer; 
| DirlD: Longint; 
CName: String[31]; 
CommentText: StringPtr); 


AddComment stores a comment string associated with a particular file 
on the volume. Unlike icons, there can.be no more than one comment 
associated with any files-1fAddComnient is called fora file whictraiready has 
an associated comment, the existing comment is replaced. ae maximum 
length of a comment string | is 199 characters. ff os 


Function RemoveComment _DTRelNum: Integer; / 
ee ‘BirlD:Lengint; =“ ¢ 
ro CName: Btring[31 y. OsEfr, 


RemoveComment removes: the comment asséciated! with a particular 
file. An error is returned:if. no comment. was stored for the file. 


Note that while the Finder will call RemoveComment to remove 
comments for files or folders when they are deleted, it does not call 
GetComment, RemoveComment and AddComment whenever a file is 
renamed or moved. If the implementation of comments relies solely on the 
DirlD/CName to keep track of comments associated with files or folders, the 
File Server will have to update its Desktop Database as part of the execution of 
the FPRename and FPMove calls. 


Function GetComment( DTRefNum: Integer; 
DirlD: Longint; 
CName: String[31]; 
CommentText: StringPtr): OSErr; 


GetComment retrieves the comment associated with a particular file. Ifa 
comment is stored, the comment text is returned. If no comment is stored for 
the file, an error is returned. 


Assembly language AddComment, RmvComment, and GetComment 


*DRAFT* 


CONFIDENTIAL APPLE COMPUTER 


calls use the following parameter block fields in addition to the basic fields 
shown earlier: | . 


AddComment, RemoveComment, and m7 


AddComment is made as an _HFSDispatch trap with D0=$28, 
RmvComment is made with D0=$29, and GetComment is made with DO set to 


$2A. 
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Introduction 


This document is a first cut at-defining the the‘Desktop Manager. for Big Bang. The new, 
Desktop Manager will be a re-implemented, enhanced version of the existing AppleShare 
Desktop Manager INIT. The new version will utilize the new BTree Manager interface being 
developed by Kenny Tung. 


The enhancements for the new version are not yet known. 
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The Macintosh Desktop Manager Interface 


by Patrick W. Dirks 
June 229 1988. 


NOTE: This document is a draft of a design in progress, and may 
change without notice in the near future. It is not meant to 
define the final interface to the proposed facility. 


1. Introduction. 


The Finder presents Macintosh user with a unique user interface 
centered around the use oe icons to td eal ae on a disk volume. TO 


ws aPPWP 9.0, 8.9,0,0,0,0.8,00. 0,0, 2.9,8,9,8,9,8,6,0,0,0,8,0.9,85° 


‘Desktop’. 
The Desktop file is. aiden Used to Perform nes, éepardte functions: 


1. To associate. ocurents atid applications with particular icons 
through its ‘bundle’ mechanism, BS well as storing the actual icon 
bitmaps, ae | 


2. To locate the corresponding application when a user opens a 
document, and 


3. To store the text of comments associated with files and folders as 
part of the information displayed by ‘Get Info’. 


The management of icons centers around the concept of a bundle, stored 
as a resource of type BNDL in an application's resource fork. The BNDL 
resource, which is identified with a particular FileCreator type can, among other 
things, refer to a number of FREF resources, which can in turn indicate that a 
file of a particular type should be displayed using a particular icon. Together, 
BNDLs and FREFs can be used to determine the icon to be displayed for a 
given file from the Creator and Type information stored as part of its Finder Info 
in the catalog. 


In addition, the Desktop file is used on HFS volumes to hold a list of 
applications stored in subfolders on the volume. The desktop contains an 
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APPL resource which is used by the finder to find an application to launch 
when a document is selected, given the document's FileCreator information. 
The APPL resource basically maps a particular Creator type to a list of 
applications that can open documents of the specified type. 


_ Finally, the Desktop file is used as a repository for the text of comments 
associated with files and folders on the volume. Comments are retrieved when 
the user selects 'Get Info’ for a file or folder, at which time the comment text 
can also be changed. 


The use of the current Desktop file structure in a Network Environment 
(i.e. on File Server volumes) has proven unsatisfactory: resource files, such as 
the Finder's Desktop file, are ill-suited for sharing among multiple users on a 
single File Server. In addition, the use of resource-file based Desktops is 
unsatisfactory for large velumes-dueto a combination -of-timitations-on the 
Resource Manager itself and efficiency of the resource structure by hundreds 
or even thousands of enttries:~ Deovavevevnyee divuvevbvatoroivorsen ; ’ "2 ¢ 


A new macheniein forthe storage ‘and scaripulaion of t this, rae 
information has been implemented for the AppleShare File Server in the form 
of a Desktop Manager, which implements a number of riew _HFSDispatch 
($Ax60) traps. This mechanism could be used transparently: ‘for local as well 
as remote volumes. The remainder of se document cull the new Desktop 
Manager calls. : , 


The Desktop file is replaced by two new files: 
¢ AB*-Tree file containing the information required to link files on the 
volume with their icons and comments, as well as to suitable 
_ applications to open a document, and 

« A data file containing the actual icon images to be displayed. 

The reason for their separation is related to the size of the icon images to 
be stored: they are too large to be kept in the B*-Tree. Since icons are never 
removed from the Desktop file in the current implementations, it is 
straightforward to allocate space for the icons in another file, and retain a 
pointer to the storage in the B*-Tree. 


This note concentrates on the interface to the Desktop Manager; it is not 
intended as a detailed discussion of the Desktop Manager's implementation. 


2. Call Interface 
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The Desktop Manager interface includes three groups of calls: 


1. Icon calls (Addicon, Geticon, and Geticoninfo), 

2. APPL calls (AddAPPL, DeleteAPPL, and GetAPPL), 

3. Comment calls (AddComment, DeleteComment, and 
GetComment). 


| Each call can be mapped into a corresponding AFP command. The 
semantics of the AFP calls parallel the semantics of the interface routines; for 
File Server volumes, little more than packing of the procedure arguments and 
unpacking of the results is required: | 


data type ResType refers-to-the- 4-byté signatures: -hat-are-part- of every file's 
Finder Information. Each file is assignedia 'File:Type’ meant to be ‘ 
representative of the nature ofthe-conterits of the file (PNTG; TEXT: ‘etc.) and 

a 'File Creator’, which is a unique-signature indicating the eoaicer which 
created the file (such as MPNT, .MACA, re) ; : 


2.1 Desktop Manager Access 

Desktop Manager elie! can bé made. ian aera (or. c) and from 
assembly language. The assembly language interface is a ‘parameter block 
based interface, quite similaito-the File System's. Déstktdp manager calls can 
be made synchronously or asynchronously. The Pascall calls are simply "glue 
routines” that set up a parameter block on the stack and make a synchronous 
_HFSDispatch ($A260) call with DO set to the appropriate selector for the call. 


The assembly language interface to the Desktop Manager uses the 
following basic parameter block layout: 


General DTMgr Parameter Block o 


(50): 

S10): aGie 

“joResult en oe ae “folndex 
40($28). 

* eBuies “DReaGaual ioActCount 


Before any Desktop calls can be made, the user must make an OpenDT 


ioCompletic 


ioTagInto 


Me 
a= 
aA 
no 
—<— 
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call, as follows: 


Function OpenDT( VRefNum: Integer; 
Var DTRefNum: Integer): OSErr; 


This call cannot be made from an interrupt. The file RefNum returned for the 
Desktop Database must be used on future calls to indicate the Desktop 
Database being referred to. If an error occurred on the call, the refNum 
returned will be zero. If the Desktop Database was already open, no error will 
be returned to the caller, and the ioRefNum field will contain the same 
DTRefNum returned on the original OpenDT call. 


When all Desktop operations have been completed, the user should 
make a CloseDT call (which takes a single argument, the DTRefNum) and 
returns an OSErr. This wittfree-altresources allocated-as-part-of the; OpenDT 
call. CloseDT cannot be called from an interrupt. This call is generally made — 
only by the Finder or at System Shutdown time; CloseDT will inimediately 
close all Desktop files and free-alt in-memory date’ structures: "Unless you're 
sure you're the first andionly user.of the Desktop Database; it's Best to leave it 
open, which is what the: Finder currently dogs, even acrogs applicanon 
launches. on ‘ 


In the assembly ienguane interface, on an OpehDT call (which is made 
as an_HFSDispatch $Ax60 call ‘with Do=$20), the ioVRefNum/ioNamePtr 
fields are used to indicate thé volurrie whose Desktop Database is to be 
opened. Ifthe call is successful (ioResult=NoErr), the ioRefNum field will 
contain the DTRefNum. This call must be made synchronously and cannot be 
made from an interrupt because it allocates and deallocates some memory in 
the system heap. 


The CloseDT call (_HFSDispatch with D0=$21) takes is DTRefNum 
argument in the ioRefNum field and returns a result in ioResult. Like OpenDT, 
this call must be made synchronously and cannot be made from an interrupt. 


All other calls can be made synchronously as well as asynchronously. 
2.2 Icon Related Calls 


Function Addicon( DTRefNum: Integer; 

| FileCreator, FileType: ResType; 
IconType: Byte; 
IconTag: Longint; 
BitmapSize: Integer; 
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Bitmap: Ptr): OSErr; 


Addicon adds a new icon bitmap to the Desktop database. The FileType . 
and FileCreator arguments (4 bytes each) specify the set of files this icon is 
associated with, while the IconType argument may indicate a specific kind of 
icon (such as color vs. black and white). Note that for a given. 

’ FileCreator/FileType, there may be a number of icons available, each with a 
different IconType. The IconTag argument indicates a Longint value to be 
associated with the icon which will be returned along with the icon bitmap when 
itis retrieved. This could be used as a timestamp, for instance, to associate 
the creation date of the application with the icons it exports. Finally, the Size 
and Bitmap arguments provide the actual bitmap in questions. Note that the 
transmission protocols impose a limit of roughly 4.5Kb on the size of individual 
icons. ee 


If an icon of the specified icon /pS ready exists for the indicated 
FileCreator and FileType, Addtcon wit! replace’ the bitmap storéd with the new 
Bitmap. An error will be returned™ ifthe. size of the’new bitmap is different from 
the size of the old bitmap. cot 5 ; 


Function Geticon( DiRetNum: nigger, 
FileCreator: ResType; 
‘FileType: ResType; 
lconType: Byte. 
Var icénTag: Long; 
Var ActualType: Byte; 
Var Length: Integer; 
BitMap: Ptr): OSErr; 


SoCo oOoCeoncconuccty 


Geticon retrieves the bitmap for a given icon, given its FileCreator, 
FileType and IconType. If no icon of type IconType is available, an 
ItemNotFound error is returned. On return, the ActualType argument is filled in 
with the type of the icon returned [this is really there only for historical reasons - 
should it be removed”? The IconTag argument is filled in on return with the tag 
associated with the icon when it was added to the Desktop database. The 
length argument used on input to indicate the size of the buffer pointed to by 
the BitMap pointer. When the call is completed it is overwritten with the actual 
size of the bitmap returned. 


Function Geticoninfo( DTRefNum: Integer; 
_ FileCreator: ResType; 
IconIndex: Integer; 
Var IconTag: Longint; 
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Var FileType: ResType: 
Var IconType: Byte; 
Var Size: Integer): OSErr; 


Geticoninfo retrieves a description of an icon, given its FileCreator type 
and a numerical index. It can be used to determine the set of icons associated 
with a given application without knowing the FileTypes in advance. Successive 
calls with increasing values of IconIndex will return information on all icons 
associated with a given Creator type. 


Assembly language Addicon, Geticon, and Geticoninfo calls use the 
following parameter block fields in addition to the basic fields shown earlier: 


7; Getlicon, and Geticoninfo: 


Addicon is made’ as ani _HFSDispatch trap with’ Do= $30, Getlcon is 
made with DO=$23, and Getlcaninto i is one with D0 set to fe 


2.3 Application Related Calis” : 


Function AddAPPL( DTRefNum: Integer; 
FileCreator: ResType; 
DirlD: Longint; 
- CName: String[31]; 
APPLTag: LongiInt): OSErr; 


AddAPPL adds an entry for the application specified by the DirlD/CName 
under the indicated ResType. The APPLTag argument is an additional LongInt 
stored with the mapping information. The application in question must exist 
when the call is made. 


There may be more than one application with same FileCreator ResType, 
although the DirlD/CName should uniquely identify the file. The Tag 
information might be used to decide among many possible applications which 
one to launch for a particular document (if the tag of the creator were stored in 
the Finder information of the document, for instance). The application's 
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creation date might be a useful tag. 


Function RemoveAPPL ( .DTRefNum: Integer; 
FileCreator: ResType; 
DirlD: Longint; 
CName: String[31]): OSErr; 


RemoveAPPL removes the mapping information for a given application 
indicated by its DirlD/CName. The file need not exist any more when the call is 
made. Note that while the FileCreator type must be specified to locate the 
entry, the application tag is not required to remove an application entry. 


It is the responsibility of the Finder (or whoever is creating or deleting 
applications) to add and remove APPL.entries for applications which are 
copied to the volume or:deleted; respéctively. For-entries‘which-are“moved or 
renamed, the Finder should remove the entry before the operation arid add a 
new entry with the updated: ‘informatiory “after the opération ‘has.beer” ‘completed 
successfully. This will avoid dncoriststengies inthe ey Database. 


Function GetAPPL( LDTAGINGD: Integer; 


_FileCreator: ResType; 

* Indéx: Integer; | 

, Var APPLTag: Longint; 
eo een eee 
CNaifie* StringPtr): OSErr:” eas 


GetAPPL looks up an application given its Creator ResType. The index 
argument is used to enumerate all application mappings stored. Indices 1 
through n will retrieve the 1St through n'h application mapping stored which are 
accessible by the caller (i.e. on an AppleShare File Server, to which the user 
has Search and Read access). Unless the caller wishes to implement a 
special selection algorithm over all available applications, a single call to get 
the first mapping should suffice to find an application which can be launched to 
open the selected document. 


Assembly language AddAPPL, RmvAPPL, and GetAPPL calls use the 
following parameter block fields in addition to the basic fields shown earlier: 


AddAPPL, RemoveAPPL, and GetAPPL: 


40(930): §2($34): 
ioDirlD FileCreator 
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AddAPPL is made as an __HFSDispatch trap with D0=$25, RmvAPPL is 
made with D0=$26, and GetAPPL is made with DO set to $27. 


2.4 File Comment Related Calls 


Procedure AddComment( DTRefNum: Integer; 
| DirlD: LongInt; 
CName: String[31]; 
CommenttText: StringPtr); 


AddComment stores a comment string associated with a particular file 
on the volume. Unlike icons, there can.be no more than one comment 
associated with any file: If AddComnient i is calledfora tile whichatready has 
an associated comment, the existing comment is replaced. one maximum 
length of a comment string | is 199 characters. oo 


Function RemoveComment( on _DTRetNum: Integer; if 
Raa “DirlD: Lengint; Fs 
ra CName: Btring[31 y. OSEM, 


RemoveComment removes: the comment asshciated! with a particular 
file. An error is returned, no comment. was stored for the file. 

Note that while the Finder will call RemoveComment to remove 
comments for files or folders when they are deleted, it does not call 
GetComment, RemoveComment and AddComment whenever a file is 
renamed or moved. If the implementation of comments relies solely on the 
DirlD/CName to keep track of comments associated with files or folders, the 
File Server will have to update its Desktop Database as part of the execution of 
the FPRename and FPMove calls. 


Function GetComment( DTRefNum: Integer; 
DirlD: Longint; 
CName: String[31]; 
CommentText: StringPtr): OSErr; 


GetComment retrieves the comment associated with a particular file. If a 
comment is stored, the comment text is returned. If no comment is stored for 
the file, an error is returned. 


Assembly language AddComment, RmvComment, and GetComment 
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calls use the following parameter block fields in addition to the basic fields 
shown earlier: . 


AddComment, RemoveComment, and meena 177 


AddComment is made as an _HFSDispatch trap with DO=$28, 
RmvComment is made with D0=$29, and GetComment is made with DO set to 


$2A. 


apple ecece acmereacerarerecaracerecererac ac ecererprerererer aie arereretetee” 
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SCSI Manager ERS 


Introduction: 


The SCSI Manager is undergoing major changes. A number of new routines are being added to improve 
performance, as well as simplify the interface to SCSI devices. 

These changes are being made for four reasons. First, the new SCSI Manager routines will provide a 
phase-driven approach to SCSI transactions, which will make the SCSI bus interface more reliable. Second, the new 
routines will provide a general interface to the SCSI hardware. Third, the changes will allow the use of 
asynchronous I/O calls. Finally, the new SCSI Manager routines will allow Disconnection/Reselection for SCSI 
devices. The overall performance of the SCSI interface will be improved through decreased transaction overhead. 
The raw data transfer rates will remain the same, although SCSI bus utilization will be increased. 

The new SCSI Manager routines will be provided as a RAM patch for the Mac Plus, the Mac SE, and the 
Mac II. It will also be provided in the ROM of future machines. 


e "SCSINewPB" and "SCSIDisposePB" Routines: 


The major oe to ihe SCSI Manager is the adciuon a a group of routines that allows the user to 
atic CReSere-peraarater-bieE Twon new routines are poe 


iZation code, or at driver Open time. The 
. Af the parameter block cannot be allocated, 
gady partially initialized -- the initial values 
sePB routine, "ptr" is a pointer to the SCSI 


e "SCSIRequestIO" and "SCSIKilIO" Routines: 


The routine that allows the user to request an atomic SCSI transaction by passing the SCSI Manager a 
parameter block is currently being called "SCSIRequestIO". The "SCSIKillIO" routine halts an asynchronous 
request. 

The SCSIRequestIO routine provides bus-level error handling that must normally be provided by a driver. 
This will help improve the reliability of the SCSI interface. In addition, use of a parameter block facilitates the use 
of Disconnection, as well as a phase-driven approach to SCSI transactions. 

An added benefit of this new routine is the hardware independence it provides. The old SCSI Manager 
interface expected to deal with the hardware directly (SCSIStat), while the new SCSI Manager interface is 
hardware-independent, allowing new hardware to be used. 

The interfaces to the routines are given below: 


OSErr SCSIRequestIO(ptr, async) OSErr SCSIKi111I0 (ptr) 
scsiPB *ptr; ScSiPB *ptr; 


Boolean async; 


The "ptr" is a pointer to the SCSI parameter block that describes the transaction. The function returns a 
result that reflects that the request was successfully queued. For SCSIKillIO, it kills the request pointed to by “ptr 
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The parameter block required by the new routine is given below: 

typedef unsigned char uchar; 

typedef unsigned short ushort; 

typedef unsigned long ulong; 

struct DCInstr { 
ulong dcAddr; /* buffer addr. or special opcode (dcLoop, dcStop) */ 
ulong dcCount; /* no. of bytes to transfer (dcMove) or loop count */ 
long dcOffset; /* buffer address offset (dcMove) or loop offset */ 
ulong dcStore; /* reserved storage (part of Saved Data Pointer) */ 

)e 

typedef struct { 
QElem *scsiQLink; /* --- link to next request block * / 
ushort scsiVersion; /* --- version of the parameter block */ 
OSErr scsiResult; /* <-~ return code from SCSI Manager */ 
uchar *scsiCompletion; /* --> address of completion routine */ 
uchar *scsiLocalData; /* --> pginter to local storage */ 
ulong scsiBus; BI bus * / 
uchar scsiReqID; SqSI ID *f 
uchar scsiReqLUN gical */ 
ushort scsiUsrFlags; user's opera its *«/ 
ushort scsiSelTO; xf 
ulong scsiReqTO; ms * / 
uchar *scsiCmdBu mand buffer pointér xf 
ushort scsiDCType Aof data-chainfng blg */ 
ulong *scsiDCInstr; ptr tlo array of gf ining instr */ 
ulong scsiDatalLe requ¢sted data Yransfey */ 
ulong scsiDatax{ hl data bytes trangferred */ 
uchar *scsiStatRuf; glus buffer pointer «/ 
uchar *scsiSnsBuy sEnse buffer i */ 
uchar scsiSnsLen; length of sen ca (at least 4) */ 
uchar scsiSnsXfer; /* <--- actual sense bytes transferred */ 
uchar scsiSnsStat; /* <-- status byte from “Req Sense" cmd */ 

} scsiPB; 


Parameter Block Fields: 


The fields in the parameter block are described below. Included is a description of the values necessary 
when the SCSIRequestIO routine is called, as well as any default values the SCSINewPB call returns. Unless 
otherwise noted, SCSINewPB sets fields to zero as a default. 

The "scsiQLink" is a reserved field. It must be set to zero when calling SCSIRequestlO. The 
"scsiVersion" field is set by the SCSI Manager when the parameter block is allocated by a SCSINewPB call. It 
must not be altered. 

The "scsiResult” field is used to return the actual result code of the SCSI transaction. It is used to report 
any errors in the SCSI protocol. It does not reflect the status byte returned from the target during the transaction. 
The status byte from the transaction is always returned in the "scsiReqStat" field. If status other than "Good" status 
is returned from a target, the "scsiResult" field will have a "bad status" value. 

The “scsiCompletion" field is the address of the driver's completion routine, if any. If the SCSI Manager 
is being called synchronously, this field will be set to zero. The "scsiLocalData” field is intended as a pointer for the 
driver's own use -- typically, a pointer to it's global data. This field is not inspected or altered by the SCSI Manager. 

Addressing the target device is the purpose of the next three fields. The "scsiBus" field is used to identify 
the physical SCSI bus that the target device is on. This field is set during the "SCSINewPB" call. The "scsiReqID" 
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and "scsiReqLUN" fields are the target ID and LUN, respectively. Legal values are 0-7 inclusive. 

The "scsiUsrFlags” field contains flags for controlling the transaction. Currently flags control the speed 
of the data transfer (fast vs. polled), control parity checking, and control device disconnection. 

The "scsiSelTO" is the select timeout for the target in milliseconds. (This field is set to 250ms by 
SCSINewPB.) The "scsiReqTO" is the overall timeout for the entire request in milliseconds. 

The "scsiCmdBuf" field is a pointer to the command bytes for this request. 

The "scsiDCType" field describes the type of data-chaining block pointed to by "scsiDCInstr". 
(Currently, the only valid type is "scsiLogical".) The "scsiDCInstr" field is a pointer to an array of data-chaining 
instructions. If no data transfer is expected (Test Unit Ready, for example,) then it can be set to NIL. 
(Data-chaining instructions are described later.) 

The "scsiDataLen" and "scsiDataXfer" fields are the number of data bytes requested and transferred, 
respectively. 

The "scsiStatBuf” field is a pointer to the status buffer for the transaction. The buffer's length in bytes 
must be equal to the number of commands in the command buffer. 

The "scsiSnsBuf" field is a pointer to the autosense data buffer. If it is zero, then the autosense feature is 
disabled. (The autosense data buffer must be at least four bytes long.) The “scsiSnsLen" field is the allocation 
length of the autosense buffer, and the "scsiSnsXfer" field is the actual amount of sense data that was transferred. 
The "scsiSnsStat" field i is the status byte fromthe autosense Request Sense call. 


Manager routines wi 
instructions. The data-ch2 : 

architecture. If an old SCSI Wane call is made, it is not serviced until all new SCSI Manager requests are 
serviced. This is because the SCSI bus cannot be freed up while the old SCSI Manager calls are being serviced. 
While the old SCSI Manager calls are being serviced or are waiting to be serviced, new SCSI Manager calls will be 
queued. After the old call is serviced, the queued calls to the new SCSI Manager routine are serviced. 
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Data-Chaining Instructions: 


Data-chaining instructions are a restricted subset of the Transfer Instruction Block instructions. There are 
three instructions, "dcMove", “dcLoop", and "dcStop". The structure of a data-chaining instruction is given above. 
The "dcAddr" field specifies the instruction type, and is considered an address unless it is one of the constant values, 
"dcLoop" or "dcStop". The "dcCount” field is a generic count, either representing the number of bytes to transfer 
(dcMove) or the number of loop interations to perform (dcLoop). It must be set to zero for the "dcStop" instruction. 
The "dcOffset” field is a generic offset. For the "dcLoop” instruction, it is the number of instructions (not bytes) to 
jump if the loop count is not exhausted. For the "dcMove" instruction, it is the offset to be added to the buffer 
pointer after the data-chaining instruction is completed. It must be set to zero for the "dcStop" instruction. The 
"dcStore” field is reserved for SCSI Manager use, and must be set to zero on entry. 


The first example is a TIB and the corresponding data-chaining block to move 4 blocks of data to disk. 
Using the fast data transfer mode, it is necessary to resynchronize at the beginning of each block. I am assuming 
512 byte blocks. 


Data-Chaining 


Opcode 


scInc 
scLoop 
scStop 


Opcode 

scNoInc buf (*) 4K buf 4K 8K 0 
scAdd (*) 8K 

scNolInc buf+4K (+) 4K buf+4K 4K 8K 0 
scAdd (+) 8K 

scLoop -40 4 dcLoop -2 4 0 
scStop _— —— dcStop 0 0 0 


If no data transfer is expected, the data-chaining block is simply a “dcStop” instruction. 
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intr ion ee adc edly Buidanirast nce 


improve the timing accuracy, and.to add’some néw capabilities to the time manager to make it more 
usable by applications. : aw ; i 


Although the new Time Manager was included with the 6.0.3 system disk to code around a bug in the 
Rockwell VIAs, the new features that were also included are not being advertised, since 6.0.3 was not 
supposed to introduce new features, so until Big Bang, or the next major system disk release these 
new features don't really exist, even though they do. . 


There have been several requests for additional enhancements to the time manager to better support 
sound and multi-media applications. These enhancements would also allow the Sound Manager to use 
the Time Manager, instead of directly accessing VIA1 Timerl. For Big Bang and the new CPU ROMs 
(Esprit, Cobra II, F19, etc.), the System 6.0.3 Time Manager has been extended to implement a 
solution that should support these requests. The section entitled The Extended Time Manager at the 
end of this document describes just these extended features. 


Documentation Errors 


There is an error in the documentation for the existing Time Manager, which has not been addressed in 
a Tech Note, although I seem to remember reading about it somewhere (maybe in an MPW release 
note). The error is in the definition of the tmCount field of the TMTask record. This field is really a 
LONGINT, and NOT an INTEGER as documented. This has been corrected in the MPW AInclude 
files for quite some time, but needs to be communicated to the development community. 
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New Features 


* RmvTime and PrimeTime now return a result code (noErr) in EepIsier DO, as the published 
documentation states. 


* Time can now be represented in microseconds, as well as in milliseconds. Negative time values 
represent negated microseconds. Positive time values continue to represent milliseconds. 


¢ The high order bit of the qType field of the TMTask record is now a flag to indicate that the task 
timer is active. It is initially cleared by InsTime, then set by PrimeTime, and cleared when 
the time expires, or when RmvTime is called. 


* The tmAddr field of the TMTask record may now be set to zero to indicate that no completion 
routine should be called. The task active bit described above can be used to determine if the time 
has expired. 


+ The completion routine is now passed a pointer (in register A1) to the TMTask record associated 
with it. This makes it possible to locate pppucAnOn, globals, and n more eusetle under Multi-Finder 
(see Tech Note #180). ree ete atuarecatne oaneretcerctaceatanraerneret : 


¢ When RmvTime is called On-an-active- ei the f imCount: ‘field of the, gMTask record will be 
returned with the amount of remaining. time that had riot been used’ ‘(in rlegative microseconds, or 
positive milliseconds). To provide the best: accuracy, the unused” time*will be returned in negated 
microseconds, if it is smal] enoustto fit in the tmCount field (arorind 35 minutes), otherwise it 
will be returned as positive milliseconds. This is true even if;'the original delay time was 
represented in milliseconds:..If the time had already expiréd, tmCount will contain zero. This 
allows the Time Manager to be used to ei cnet Hmes igescuibed below), which i is useful 
for performance measufements, 


H r 
coo oOo oo oncoty 


New_ Restrictions 


¢ Calling PrimeTime on an TMTask record who's time has not expired yet will yield 
unpredictable results. This is not really a new restriction, but it was never explicitly stated before, 
and yields different unpredictable results in this version. In this situation, you would need to call 
_RmvTime to cancel the prior request, InsTime to reinstall the timer task, and then the 
_ PrimeTime may be performed. It however is possible, and sometimes even desirable, to call 
_ PrimeTime in the completion routine of the TMTask that you want to re-prime, since the 
TMTask will have expired before the completion routine is called. 


* In order to provide resolution better than one millisecond, the maximum delay time was reduced 
from about 24 days (which was not explicitly documented), to about 1 day. Larger delay times 
may still be specified to PrimeTime, but they will be converted to the largest possible time 
instead. It is unlikely that this will cause any problems. 


* The meaning and usage of Time Manager's private variables in the system heap, has changed 
completely. Nobody outside of the Time Manager should ever depend upon their prior, current, or 
future usage, or even access them. 


¢ The Time Manager now uses some of the bits in the OType field of the TMTask record, usage of 
this field was not previously documented, and should now be considered reserved. 
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Range, Resolution and Accuracy 


The Time Manager represents time in several ways. The external programming interface uses a 32 bit 
longword value, which when positive represents milliseconds, and when negative, represents negated 
microseconds. This representation is used as the delay time input to PrimeTime, and as the 
unused remaining time output by RmvTime. | 


The VIA1 (6522) Timer2 is the 16 bit hardware timer used by the time manager. On all current 
machines, it decrements at a rate of 783360 Hz, and generates an interrupt, and keeps counting, when 
it counts through zero. This provides resolution of 1.276 usec, and a range of 83.660 msec. Times 
longer than the VIA maximum are broken down into several intervals of maximum time, followed by 
an interval of the remaining time. 


Internally the time manager represents time as a virtual unsigned 36 bit VIA timer, which gives a range 
of about 1 day. However, since we only have 32 bits to store time in, we drop the low 4 bits of the 
timer, which reduces the resolution by a factor of 16 to 20.425 psec. 


Converting between the external and internal forms of time is done by multiplying by the proper fixed 
point constants, and shifting the binary point’of'the 64 bit result to get just the integer portion of the 
result. : : H : 


All internal time computations aré d6né tsifig the interdal form of time, which’ is an improvement over 
the old time manager, since partial.milliseconds are not lest, however there 18 potential for small losses 
of accuracy due to truncation in time computations, but they should’be limited to a few of the 20.425 
[sec internal ticks. The time mariager‘also needs to momentarily stop and resume the VIA timer, 
whenever PrimeTime, RmvTime, or a timet interrupt ogcurs. When this happens, the Time 
Manager will try to accurately account for the time:that the tinier was’stopped, and should give fairly 
accurate long range results. F i : - i 


Although I have just documented the current exact internal fange and resolution of the time manager, © 
this information should be considéred-undécumented, and model dependent. This is so that we are not 
tied to the current VIA clock rate, in case future hardware changes this, and so that we have flexibility 
in the future to change the range / resolution tradeoff. It would be safe to document the range as 
"Several hours", and the resolution as "better than 250 useconds". It should be OK to disclose exact 
information for people who want to do performance measurements on a specific machine / system disk 
combination, with the understanding that it may not apply on other configurations. Third Party 
Applications should NEVER depend upon the exact times, since they are expected to run on a variety 
of hardware / software configurations. 
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Computing Elapsed Times 


An exciting feature of the new Time Manager is the ability to compute elapsed times, which is very 
useful for performance measurements. This is done by calling PrimeTime at the beginning of the 
interval to be measured, passing in a delay time greater than the expected elapsed time, and calling 
_RmvTime at the end of the interval, and subtracting the unused time returned in tmCount, from the 
original time passed to_ PrimeTime. For best accuracy, all timing should be done representing time 
in microseconds (which has a range of 35 minutes), and the overhead associated with the time manager 
ae be computed and subtracted from the final result. The following code sample demonstrates the 
technique. : 


: Allocate and clear a tmTask record on the stack, tmAddr := 0, no handler. 


moveq.1 #(tmQSize/2)-1,da0 ; setup loop counter to clear tmTask 

@clear clr.w -(sp) ; allocate and clear a tmTask 

dbra do, @clear ; clear it a word at a time 

move .1 #60*1000*1000,d7 ; D7 := delay time in psecs (1 minute) 
movea.1 sp,a0 ; AO points to the tmTask 
_InsTime pemeony ; install the task 
move.l hyde eee eT i : DEwr=copyof “initial de lay time 
move.1 g7,.a0 } ; BO := delay time H 
neg.1l 0 ee ; Aegatg...it..to..represent .fiseconds 
_PrimeTime : : ; start the timer 7 
_RmvTime i t cant ; “Ymrlediately stop its 


add.1 tmCount (a0) ;'a7 *, ¢ D7 := init¥al de}ay ~ time remaining 


movea.1 &sp,a0 % i _ #3 AO poigts to the tmTask 


_InsTime : a fo insta} the task 

move .1 “d6, dO “rene  ; DO :=delay time 

neg.1 dO enc ae ; negatie.it.tejrepresent pseconds 
_PrimeTime rs ; start the timer 


; code to be timed goes here (in this example a TimeDBRA loop) 


move .w TimeDBRA, dO ; number of DBRAs per millisecond 
@dbraLoop dbra a0, @dbraLoop ; waste a millisecond 

_RmvTime ; stop the timer 

add.1 tmCount (a0) ,d6 ; D6 := time used in pseconds 

sub.1 a7, dé ; subtract the time manager overhead 

adda.w #tmQSize, sp - ; de-allocate the tmTask 


7 Register D6 contains the number of microseconds used by the timed code. 


If you actually run this code, you may notice that on some models of the Macintosh, register D6 is not 
very close to 1000 (1 millisecond). This is not due to a problem in the Time Manager, it is because 
_ ‘TimeDBRA is the number of DBRAs per millisecond when executing out of ROM, and RAM accesses 
have different timing on some models. Additionally, this example should not be run on a Mac Plus, 
since the variable TimeDBRA is not supported by that ROM. 
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Resolved Issue 


The first issue is which register should contain a pointer to the TMTask record when the tmAddr 
routine is called, when the timer expires. Register AO makes the most sense, since it is the register 
used in all of the calls to the Time Manager. However, on page 8 of Tech Note #180, in pointing out 
the deficiency in the old Time Manager that is being addressed now, it states "a Time Manager task is 
not called with AO pointing to the task block (AO points to the task's routine instead)". This statement 
now documents what was previously undocumented, by stating that AO will contain a pointer to the 
routine. Additionally, a system file patch for ADB mouse de-bouncing, uses the Time Manager, and 
assumes that AO contains a pointer to the task's routine. This patch can be modified to not depend 
upon this "feature" at the same time that the new time manager is incorporated, but it makes you 
wonder who else might depend upon this. So the question is, should the pointer to the TMTask 
record be passed to the task in register Al, or AO? 


Resolution: Use the most compatible solution, passing a pointer to the TMTask record in Al, and 
continuing to pass a pointer to the task’s routine in AO. 


aguiececaretecerscecerecatete;elerecacetet ataes a aces etasecerecare: areca etetet” 


cause problems in the future. 


The final issue is the resolution vs. range tradeoff. Since we only have a 32 bit field to store time in, 
we have to trade off between fine resolution, and extended range. The old Time Manager had a range 
of about 24 days (which seems excessive), and a resolution of one millisecond. Better resolution was 
desirable, and range needs to be sacrificed to obtain it. How much range should we sacrifice to get 
better resolution (2 day/4ips, 1 day/20ps, 12hrs/10psec, 6hrs/Spsec)? Better resolution provides 
more accurate time computations, and better elapsed time measurements. Sacrificing range may start 
running into compatibility problems. What is the best tradeoff? 


Resolution: The Time Manager will use a range of 1 day, with resolution of 20sec. 
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Bug Fixes 


There were a number of bugs fixed in this revision, most of them were never reported, and probably 
difficult to reproduce. They are documented here for the benefit of those who may run into them with 
older system disks, or have decided not to use the Time Manager in the past because of them. All of 
them are fixed in the new Time Manager. 


The size of the tmCount field is incorrectly documented, it is a LONGWORD. 


If the tmCount field was non-zero when _InsTime was called, the task may sometimes run, 
even though PrimeTime was never called. 


_RmvTime did not return a result code in register DO. 


If RmvTime is called on an active task, and other Time Manager tasks are also active, it is — 
possible that the other tasks may run as much as 83 milliseconds later than they were scheduled to 
run. 


were disabled. 
_PrimeTime may sometimes destroy. registers A3 and D3. ye 


_PrimeTime with a time délay of zero would never rug, it now runs as soon as interrupts are 
enabled. t i - 2 f : 


If PrimeTime is called Gn-a.new.task;‘ind another task-is-already scheduled to run sooner, it is 
possible that the later task may have run as much as 83 milliseconds earlier than it was scheduled to 
run. 


In PrimeTime when the VIA timer is read, it was possible to sometimes have an error of 256 
ticks (326j1sec). 


If a higher priority interrupt, interrupts the timer interrupt before it has a chance to disable 
interrupts, and the higher priority interrupt handler calls PrimeTime, or_RmvTime. When the 
higher priority interrupt handler returns, it is possible that the timer interrupt handler will run a task 
as much as 83 milliseconds too early. 


There appears to be a bug in VIAs manufactured by Rockwell, and some other vendors, which 
would cause a timer interrupt to get lost, which would cause the Time Manager to not run any 
tasks. A software work around for this problem has been incorporated into the new Time 
Manager. 
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The Extended Time Manager 


There have been several requests for additional enhancements to the time manager to better support 
sound and multi-media applications. These enhancements would also allow the Sound Manager to use 
the Time Manager, instead of directly accessing VIA1 Timer]. For Big Bang and the new CPU ROMs 
(Esprit, Cobra II, F19, etc.), the System 6.0.3 Time Manager has been extended to implement a 
solution that should support these requests. The new functionality provides the ability to have drift 
free fixed frequency timing services. The implementation of these features requires an expanded 
TMTask parameter block, and an altemnate trap (which has the same trap number, but uses different 
flag bit encodings in the trap word) to install the expanded timer task, which are only needed if the new 
features are desired. The extended TMTask record and trap are defined below. 


TMTask record 0,increment 

qLink ds.l si ; next queue entry 

qType ds.w 1 ; queve type (used internally by Time Manager) 
tmAddr ds.l 1 ; pointer to service routine 

tmCount ds.l 1 ; time remaining from _RmvTime 

tmOQSize equ * : size of standard TMTask 


> new fields used by exten ded time-manager™ are iy below rveesencenceecentintentsieneeniceneuneninceentoteg 


tmWakeUp ds.l a 7 wakeup time, (used internally by Time Manager) 
tmReserved ds.1 a svevvoreeeeevetenes PRT I eser veo fo Lp LULU TEMES ong: ; 
tmxQSize equ * : ; size of extended TMTask* 
en dr < 3 fee ny eee ees! aa 
_InsxTime OPWORD sags ; ingtall extended Mrask,* 


With the standard time manager,.the delay time passed to _PrimeTiine indicates a wakeup time that 
is relative to current time. :This presents problems when a drift free’fixed frequency timer service is 
desired, by having the timer service routine reissue a_PrimeTime,since time consumed by the time 
manager, and any interrupt latency (Which is not predictable), would cause the service routines to be 
called at a slightly slower and uiipredictable frequency, which would drift over time. 


The extended Time Manager solves this problem as follows. When an extended Time Manager task 
has been installed (using _InsXTime) the behavior of PrimeTime is changed slightly. If the 
tmWakeUp field is zero when PrimeTime is called, the delay will be relative to the current time 
(just like in the standard time manager), but the Time Manager will set the tmWakeUp field to a 
non-zero value which indicates when the delay time should expire. Non-zero values in tmWakeUp are 
in a format that is only used internally by the Time Manager and may be subject to change, applications 
should never use the values stored in this field, and should either set it to zero, or leave it unchanged. 
When an extended TMTask record is first created, care should be taken to ensure that the tmWakeUp 
field is initialized to zero, otherwise the time manager may interpret it as a prior wake up time. 


When PrimeTime is called with the tmwakeUp field non-zero, the delay will be relative to the time 
that the last_ PrimeTime on this TMTask was supposed to expire, instead of being relative to the 
current time. For example, if a 1 millisecond delay is requested, but the last_PrimeTime was 
supposed to expire 100 microseconds ago, the actual new delay will be for 900 microseconds. 


Similarly, the extended Time Manager can be used to read the time remaining for a TMTask, using 
_RmvTime, and then by issuing an_InsXTime, anda_PrimeTime witha delay of zero specified 

in DO, leaving tmWakeUp unchanged, the task will continue delaying until the time specified by the 
original PrimeTime has expired. This can be used to acquire high resolution time stamps. 
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There is a situation that can occur when using the extended Time Manager, that was not possible 
before, and may lead to undesirable results. It is now possible fora PrimeTime to be issued where 
the desired wake up time is in the past, instead of in the future which is the only possibility in the 
standard Time Manager. This situation arises from the case where the tmWakeUp field is sometime in 
the past (which is most common in the tmAddr service routine), and anew _PrimeTime is issued, 
with a delay value that is not large enough to cause the wake up time to be in the future. This may 
occur where fixed high frequency wake ups are required, and the time needed to process each wakeup, 
including the Time Manager overhead, is greater than the delay time between wakeup requests. _ 


When a_ PrimeTime is requested with a negative delay time, the actual delay time will be zero, and 
tmWakeUp will be updated to indicate the time that the task should have waken up (which is in the 
past). By continually issuing PrimeTime requests for times in the past, all of the processor cycles 
will be consumed by the Time Manager, and the tmAddr service routine, and no time will be left for 
the application to run. This situation is a function of processor speed, applications that use these 
features should be tested on the slowest processor to ensure compatibility, or perhaps vary the wakeup 
frequency depending upon the power of the machine. 


POOR 
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The following routine can be usedto'determine at exécutiofi titié Which’ Version of the time manager is 
available, and what it's limitations-are...It will return.the time mamager,Version, and the maximum 
number of milliseconds of delay that can be-used. The Standard‘Time*Manager contains just those 
features documented in Jnside-Macintosh Volume IV. The Revised Time Manager contains the 
additional features described.in this do¢ument, except for those’ described above in the Extended Time 
Manager section. The Extended Time Manager contains all of the additional features described in this 
document. e % Z : ? : 


If an application needs to,use véry-tong Time“Manager delays (several hours), it should check to see 
what the maximum delay time. the time-mianager supports.is,.and may need to issue several shorter 
delays in order to delay the desired amount. This is needed because the Time Manager has a limited 
delay range, and if a request exceeds the limit, the maximum supported delay time will be used instead. 


Although the Time Manager now supports delay times represented in microseconds, this feature is 
mainly intended to allow measuring of elapsed timing with finer resolution. Developers should be 
aware that repeatedly specifing very small wakeup times to acheive high frequency wakeups, will use a 
considerable amount of processor time which will vary depending upon the performance of the CPU, . 
and may leave little or no time for other processing on the system (like moving the mouse, or running 
applications). 
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include 
include 
include 


'Traps.a' 
'SysEqu.a' 
'TimeEqu.a' 


TimeMgrInfo - Pascal callable routine to get Time Manager Information 


; TYPE TimeMgrVersions = 


(Standard, 
Revised, 
Extended); 


3. PROCEDURE TimeMgrinfo 


TimeMgrinfo 


@Prime 


@Remove 


@Done 


proc 
suba.w 
movea.1 
clr.l 
move .wW 
_InsTime 
move.1 
moveq.1 
move.b 
bmi.s 


addq.1 
add.b 
bmi.s 
addq.1 
move.1 
clr. 1 
_PrimeTime 
_RmvTime 
tst.b 
beq.s 


move.l 
bpl.s 


neg.1 

move.1 
clr.w 
swap 

divu.w 
eor.w 
eor.w 
eor.w 
divu.w 
swap 

move .w 


adda.w 
movem.1 
move .1 
movea.1 
move.b 
jmp 

end 


{ original pre 6.0.3 version } 


{ version introduced in 6.0.3, better resolution, elapsed timing } 
and Big Bang version, 


{ new ROMs, 
(var version : 


export 
#tmOSize,sp 
sp, a0 
TMCount (a0} 


#SFFFF, OType (a0) 


#S7FFFFFFF, dl 
#0,d2 


OType (a0), "dO. — 


bRemove 


tmCount (a0),dal 
@Done 


di 

d1,d0 

do 

a0 
#1000,d0 
di,do 
do,dl 
di, do 
#1000,d0 
dl 

do,dl 


#tmQSize, sp 
(sp) +,a0/al 
di, (al) 
(sp)+,al 
d2, (al) 

(a0) 
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se Pt et iT al ar +set 
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drift free timing features } 


TimeMgrVersions; 
var MaxMilliseconds ;: 


Longint); EXTERNAL; 

allocate a TMTask 

pointer to task for time manager traps 
avoid bug in Standard Time Manager 

set all bits of QOType 

install the task 

max time of standard time manager 


emgheti tat 


“as sume version is standard version 
should bie “unchanged _ ‘on std “time mgr. 
it stilt fedatt Ver : 


must be staj time mor. 


“next Manos: bit ungvangeg’ on revised version 


will be cleared on; fextended version 
version must be ektended version 

attémpt to use Fargest/ ‘milliseconds value 
no gompletion youtine/ 

start the timér 

stére timer and remove the task 


wtheck for standard tiime mgr. 


if standard,“max” “tfsttie is constant 


get time remaining, which is close to max 
if positive, it's already milliseconds 


make it positive microseconds 
save a copy 

clear low word 

get high word, zero extended 
convert high word to milliseconds 
exchange low words of d0,dl 


convert low word to milliseconds 
move high word of result to high word 
insert low word of result 


deallocate the TMTask 

pop the return addr, max delay pointer 
return the max delay time in milliseconds 
pop version pointer 

return the time manager version 

return 
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HDSC Setup ERS 


Code: HDSC Setup 
Version 2.xd1 
Date: Sat, Jan 14, 1989 


Author: Andy Gong x4-6595 


Abstract: | 
HDSC Setup is Apple's application to format, test, and partition hard disks. Current 
system disks, shipped with each Macintosh, contain this utility program on both the 
System Tools disk and the System Utilities disk. For a user to begin using their new 
Apple hard disk drive, he or she must first execute the HDSC Setup application. 
HDSC Setup initializes and formats the disk. In addition to those two actions, HDSC 
Setup loads a driver onto the hard disk. The driver will be used by the system to access 
the hard disk. The application consists of a user interface (written in Pascal), and lower 
level intermediate code (written in C and assembly) which does the actual interfacing to 
the system SCSI Manager. 


2. Introduction 


HDSC setup 2.0 will be undergoing various changes to enhance its current capabilities . 


2.1. Disk Driver Changes 
The HD SC driver is currently part of the HD SC setup application. Changes are 
being made to enhance the drivers feature set. These changes are detailed in the 
"HD SC driver ERS' document. 


Besides just the driver changes itself, HD SC setup will have the ability to ‘find' a 
disk driver file in the system folder. This would allow updates of the driver alone. 


2.2. New SCSI Manager Trap 
HDSC Setup is written to interface with the system SCSI Manager. As dictated 
by the current SCSI Manager design, the calling software handles most aspects of 
a SCSI transaction manually. The code consists of multiple calls to SCSI Manager 
routines, and extensive error checking to insure correct transactions. A new SCSI 
Manager routine (or trap) will provide an easier, more consistent, and more 
flexible interface for both the calling application and the SCSI device on the bus. 
HDSC Setup is being revised to utilize the new SCSI Manager trap. 


) 
arket, Apple is beginning to 
use in products. These drives 

second rdrive products. At the moment, 

support for each additional new drive requires changes to HDSC Setup. Although 
the ‘drive resource' change mentioned above will ease the impact of the changes, 
the timing of releases of HDSC Setup coincides with the system disk. This 
unnecessarily ties the schedule of the hardware drives to the system disk. To 
change this interdependency, a new method of supporting hard disk drives will be 
used. Additional information will be stored on Apple approved drives. This 
information will be similar if not the same as the information currently being stored 
in the Disk Drive Data resource (as mentioned above). Given this information, the 
software will immediately be able to support the new hard disk drives. 


3. Interfaces 


3.1. User Interface 
In general, the user interface of HDSC setup will not change. All of the changes 
will be a restructuring of the existing HDSC Setup code, and enhancements 
outside of the HDSC Setup code. Note that this statement is true for the 6.0.4 (7) 
release of the application. For 'Big Bang’, there will be changes to the application 
and its user interface. The decision to update the user interface was just made so 
there is no specifications on what will be the new user interface. 


3.2. Software Interface 


4. Description 


The proposed changes to HDSC Setup are completely invisible to all users. Changes to 
the disk driver and internally to HDSC Setup will have NO user visibility. The user 
will not notice any difference from the old HDSC Setup. The enhancements are to allow 
easier maintenance of the code, support of the new SCSI manager, and (hopefully) more 
reliable code. 


4.1. Disk Driver Changes 
See 'HD SC Driver ERS'. 


4.2. New SCSI Manager Trap 
The SCSI Manager is currently being revised to provide an ‘all in one’ SCSI 
transaction trap. In one call, this new trap will provide all the code necessary to 
complete one entire transaction. In general, a SCSI transaction comprises of 
multiple separate and different data exchanges. These data exchanges could be 
control messages sent to the device, control message read from the device, status 
message from the device, user data and so on. These data exchanges are 
considered as pier ‘phases’ of a transaction. The new call will be more 
fle action 4 yet creater latitude in terms of 
gresseg through the different SSI phases. Additional 
lew SCBI Mang drt of the ‘disconnect’ 


3 be freed up for other uses ~ 
takes an extended period of 
ard disks and rewinding tape 


‘gall i is Ceeoed If so, the 

pplitesi oEv re sively for all transactions. If the trap 
is not present, the application/driver will revert to the older type SCSI calls to 
complete the transaction manually. 


4.3. SCSI Disk Resource 
The current version of HDSC Setup uses an internal ‘hard coded" table of disk 
drives to recognize and deal with. Other tables contain the detailed information 
about all the different disk drives we support including what we consider ‘generic’ 
Apple approved disk drives. 


In an effort to separate the algorithmic part of HDSC Setup from the drive 
configuration information, a new resource will be created to contain all the 
information which describes the unique parameters for each disk drive. The 
creation of this new resource allows for the addition of new drives without 
recompiling and retesting the code. To add a new drive to the list of supported 
drives takes only a few minutes. It involves creating the new resource entry 
which describes the new disk. 


4.4. HD SC auto ssnheuralion (PROPOSAL ONLY) 
Auto configuring hard disk drives is a new concept being investigated. Right 
now, support for hard disk drives is directly tied to HDSC Setup. The concept for 
auto configuring hard drives, and thus providing immediate software support, 
stems from extending the resource information into the disk drive. Basically, the 
unique disk drive parameter information would be stored in ROM within the drive. 


5. Issues 


With the resource type information on the drive, the software will be able to read 
the parameters (just like reading the drive resource), and initialize the drive based 
on this information. The SCSI command (mode select) which would be used to 

read the information is REQUIRED by all Apple Approved disk drives. 


Since this information will only reside on newer drives, the disk initialization 
routines (HDSC Setup) will support two different methods of getting disk drive 
parameters. The first place the software will search is the disk resource 
information in the system file. If the information is not found there, the software 
will proceed to attempt to read the information from the new page on the drive. 
The order for which we search for information is important. It allows the “hard 
coded” parameters on the drive to be overridden. This may be necessary if, down 
the road, a problem is discovered with the built in parameters. 


Currently there are no open issues on HD SC setup. 


FDSGC Driver ERS 


Code: HDSC Setup 
Version 2.xd1 
Date: Sat, Jan 14, 1989 


Author: Andy Gong x4-6595 


Abstract | 
In the current Macintosh computer line, one of the major peripherals in use is the hard 
disk. The hard disk provides a computer the services of large amounts of secondary 
storage (non volatile) at moderate speeds (milliseconds). Hard disks are connected to 
the Macintosh through a somewhat standard electronic bus (SCSI). This bus provides 
an 8-bit communications between SCSI devices (such as hard disks) and the host 
computer (such as the Macintosh). As with any I/O device, peripherals using the SCSI 
bus must have a software driver in the host computer to provide a communications path. 
The HD SC driver is Apple's Hard Disk driver. 


2. Introduction | 
The SCSI disk driver code is implemented as a standard driver with additional code 
necessary to make the driver bootable. The additional coded is used to install and 
configure the driver. The driver install code surrounds the entire driver code. 


Apple's hard disk driver is currently undergoing modifications to support the ever 
changing world of system software (in particular, the new SCSI manager and SCSI 
rover), fix bugs (of which one corner case was found), and provide new features. This 
document will provide a general description of the "features" which the new HD SC 
driver will support. | 


The HD SC driver is written to interface with the SCSI Manager. As dictated by the 
current SCSI Manager design, the driver handles most aspects of a SCSI transaction 
manually. The code consists of multiple calls to SCSI Manager routines, and extensive 
error checking to insure correct transactions. The new SCSI Manager will augment the 
feature set with a new entry point (routine, trap, ...) which will provide an easier, more 
consistent, and more flexible interface for both the calling application and the SCSI 
device on the bus. The HD SC driver is being revised to take advantage (when 
possible) of the New SCSI manager. 


ATSTOr TOrmat and verity’. In the future, 
these calls wou the disk forma} package (PACK2) to initialize hard disks. 


3. Interfaces 


¢ Ope =Mark the driver if Ws¢, allow the driver to initialize. 


¢ Close - Mark the driver free, release resources. 
¢ Control - Change aspects of the driver or hardware 
¢ Status - Current state of driver or hardware 

¢ Prime - Data transfer routines (Read/Write). 


Software access to these entry points are made via the 'OPEN', 'CLOSE', 
‘CONTROL’, ‘STATUS’, 'READ', and the "WRITE ' traps. 


The parameters which are passed into these different entry points are a pointer to 
the called DCE and a pointer to the I/O parameter block. These pointers are passed 
in via the Al and AO register respectively. 

4. Description 


4.1. Driver Installation 
The installation of hard disk drivers is similar to that of drivers on NuBus cards. 
The boot code explicitly makes a separate effort to search for hard drives on the 
mother board SCSI port. If a drive is found, the boot code validates the drive by 
reading block 0 on the drive (this is the Driver Descriptor Block). The 'Erich 
Ringewald’ memorial signature is then checked. If the signature is correct, the 
blocks containing the prospective driver and its install code is read into memory. 
The boot code then passes control to the install code. 


The install code has two main functions. The first is to check for errors during the 
read of the driver. Checking for errors is done via a checksum. If the checksum 
matches up, the code installs the driver into the unit table. The new driver will be 


using an AUXDCE as its DCE. This is to provide more flexibility and information 

of the driver. The second function of the install code is to open the disk driver to 

allow system access. Since nothing else is responsible for ‘opening’ system 

drivers of this sort, the install code must open the disk driver. 

4.2. Open 
4.2.1. Function 

As in all drivers, this is the first routine called before the driver is usable. In 
the disk driver case, the open occurs automatically at boot time as described in 
the ‘Driver Installation’ section of this document. The open routine basically 
allocates private storage, obtains a SCSI parameter block for communications 
with the SCSI manager, initializes the state of the driver, sets up a VBL and 
Shutdown task as needed, and post a disk inserted event if requested. 


4.2.2. Errors 
No Error (0) 


This is the standard return valid if all went well. 
openErr (-23) | 

An openErr is return to the caller if one of two things fail. On open, the 
_ driver will attempt to allocate local private data storage necessary for the 

_ driver to function. If the attempt to allocation the memory fails, the 
~ openErr will be returned. The other reason for a failure to open is if no 
valid driver or Pannen information is found. This would mean that 
DDM) is invalid, or the partition map is 


4.3.2 


4.4. Contrd 
The new disk driver will support the control calls for Accessory Run, Verify, 
Format, Get Icon, Eject, and a call to enable/disable Physical to Logical Block 
mapping. 

4.4.1. Error 

No Error (0) 
This is the normal return code if the requested action is completed 
correctly without error. This return code implies that the control call was 
implemented in some way. The implementation could be a no op. 

nsDrvErr (-56) 
Since this is a driver for a hard disk, the I/O parameter block should 
include the drive number which is being called. If the drive number in 
the parameter block differs from the drive number assigned by the driver, 
this error is returned to inform the calling software that the is no such 
drive. 

verErr (-84) 
For some background, verification of a SCSI hard disk requires multiple 
SCSI transactions. Each transaction verifies only part of the disk drive. 
This error is returned if a verification command encounters errors. Such 
errors include unrecoverable errors in the during the SCSI transaction, or 
greater than 4 retries of a specific SCSI transaction. 

fmtlErr (-82) 
The format control call would return this error if one of three different 
actions fail. The format command to the disk drive could have failed or 
timed out. The partitioning information could not be written out to the 


disk. And last, if the partition information on the disk was found 
invalid. Any of these three errors would cause this error to be returned 
to the calling software. 
controlErr (-17) 
If an unsupported control call is made, this is the error which will be 
returned to the calling software. 
4.4.2. Accessory run 
The SCSI driver uses the accessory run call to signal the driver that patches 
are installed. The driver uses this signal as an indicator that the system is 
reasonable stable. With patches in, the driver checks for the existence of the 
Shutdown Manager, and the New SCSI manager. With the existence of 
either, the disk driver will take action to reconfigure its method of operations. 
4.4.3. Verify 
The verify routine has the job of validating all the physical blocks on the disk. 
This control call will be necessary to correctly support the disk formatting 
package in PACK2. There are two different methods of validating a block on 
the disk. If the Disk supports the SCSI 'verify' command, then the SCSI 
command would be sent for all the disk blocks. If the SCSI ‘verify’ 
command is not supported, then the code will 'read' all the blocks on the 
disk. The action of reading the blocks will cause the disk drive to perform a 
checksum on the blocks being read. If errors are found, the drive will attempt 
to correct Bk errors if passible. In either c case, if recoverable errors are 


One question which must be determined BEFORE any formatting occurs 
is whether the entire disk should be formatted. Since the control call will 
be made from both PACK2 and from the ‘erase disk’ pull down menu, a 
determination must be made when the disk should be formatted. Only if — 
PACK2 makes the call should the format occur. 

Configure Drive 
Before formatting a disk drive, control information must be written to the 
writable control store on the disk controller board. This information in 
the writable control store may be used by the disk controller during its 
execution of the format command. 

Format 
The actual formatting is simply done by sending a SCSI ‘format’ 
command. Results of the format command will indicate whether the 
format was successful or not. If the format was not successful, the 
format control call is immediately terminated with an error. 

Partitioning 
After formatting a disk drive, the disk remains useless to the system until 
certain information is placed on the disk. Among the information which 
must be written to the disk is the partitioning data. These data structures 
act as a directory describing how the disk drive has been divided into 
groups of blocks (or partitions). The complete set of partition map 
entries MUST account for all the blocks on the disk except for BLOCK 


0. The disk driver will layout a default partition map which will include 
4 entries, 


1) . Partition Map Area 

2) Driver Area 

3) HFS Area 

4) Free Area (from the old days, may be removed). 

Write Driver 

As was mentioned in the Driver Installation’ section, the driver for the 
disk comes from the disk itself. This method is used to allow auto 
installation of the driver on boot, and therefore allowing booting from 
hard disks. The Driver Descriptor Map is written onto BLOCK 0. The 
DDM is used as a data structure which describes the location and size of 
the driver on the disk. The driver and driver data which is to be written 
to the disk is obtained directly from the driver currently being called to 
perform the format. 


4.4.5. Icon 


This control call is used to provide the caller with a custom icon for the media 
which the driver communicates with. The driver will return a pointer to the 
hard disk icon. 


4.4.6. Eject 


This call should never occur. Since the drive is marked as non-ejectable, the 
system should never make this control call. (This routine may be removed on 


in the future). 
4.4.7. Physical to Losigal eee 
Mis comror call is a driver/Spe h changes the driver 
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4.5. Statu 


‘No Error (0) 
This is the normal return code if the requested action is completed 
correctly without error. This return code implies that the status call was 
implemented in some way. The implementation could be a no op. 
statusErr (-18) 
If an unsupported status call is made, this is the error which will be 
returned to the calling software. 


4.5.2. Driver Status 


The drive status call is used to be general (up todate) information on the disk 
drive. 


struct DrvStsSC 


char writeProt; /* bit 7=1 if write-protected */ 

char diskInPlace; /* 8, for non-ejectable disk */ 

char _ installed; /* 1, for drive installed */ 

char _ sides; /* 0, unused (same as HD20) */ 

DrvQE] gel; /* the normal drive queue element */ 
struct DrvQEl 


structQElem *qLink; 


short qT ype; 


short dQDrive; the drive number 
short dQRefNum; driver ref number 
short dQFSID; file system ID 
unsigned short dQDrvSz; number of blocks low 


- unsigned short dQDrvSz2; number of blocks hi 


. 
? 


4.6. Prime | 
Prime is the main entry point for all data transfers. The 'Read' and ‘Write’ traps 
will eventually call the prime routine to perform the required action. 


4.6.1. Function | 
The prime routine basically checks for errors, moves the requested data, 
retries On errors, remaps bad blocks found, and updates the iopb on exit. On 
receiving the I/O parameter block, the prime routine does a cursory check of 
the parameter block for any obvious errors. If no errors are found, the 
read/write is attempted. If recoverable errors are encounter during the 
transaction, the transaction will be retried a maximum for four times. If a bad 
block is encountered during the retries, the prime routine will attempt to 
relocate the back block before continuing to retry. The retry count is reset 
each time a new block is remapped. If the prime routine finally completes 
without error, the I/O parameter block is update to reflect the completion. 


The prime code Mine be altpred to pitilize the full epee of the SCSI 
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One? we added to thp driver if the ability to support 
asyachront rs-eaH e disk driver wi € to support asynchronous call 
if and only if the New SCSI manager is installed. If an asynchronous call is 
made to the disk driver, the disk driver will call the SCSI manager 
asynchronously. In this case, retries will not function and the completion 
routine will take care of updating the I/O parameter block. 


4.6.2. Errors 
10Err (-36) 


I/O error is return for only two different reasons. One is if the disk is 
unformatted, the driver will not allow prime routine calls. Instead, ioErr 
is returned. The second reason is if the SCSI transaction failed and was 
not recoverable, or the number of retries has been exceeded. 


nsDrvErr (-56) 
Since this is a driver for a hard disk, the I/O parameter block should 
include the drive number which is being called. If the drive number in 
the parameter block differs from the drive number assi igned by the driver, 


this error is returned to inform the calling software that the is no such 
drive. 


parameterErr (-50) 
Parameter block errors are the result of failing the bounds checks. The 
first bounds check is made to insure that the request is on a block 
boundary. The amount of data requested must be an integral value of 
512 bytes. The second bounds check is made to confine the read/write to 
only the HFS partition. If the read/write is outside of the HFS partition, 
the request will be rejected. | 


4.6.3. Completion 
The completion routine has the responsibility of checking the result of the 
SCSI manager request. If all went well, then the I/O parameter block is 
update to indicate the data was moved. JIODone is then jump to with the 
result set in DO. 
5. Issues 
5.1. Reentrancy 

The major issue with the current driver is its ability to be fully reentrant. The need 

arises from the onset of Virtual Memory. The VM system will have to be able to 

call the disk driver prime routine immediately on a fault of memory. Currently the 

only obstical for full reentrancy (without qualification) is the method in which 

parameter blocks (for the new SCSI manager) is generated. Some compromises 

will have to be made. This may mean qualified reentrancy (the prime routine can 

only be reentered n different times), or some other change. 
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Code: HDSC Setup 
Version 2.xd1 
Date: Sat, Jan 14, 1989 


Author: Andy Gong x4-6595 


Abstract 
In the current I/O model, device drivers are configured into the system in various ways. 
The simplest method is used by drivers like the floppy disk, apple desktop bus, and 
other system drivers. These drivers are fundamental to the system and are installed in 
the start code of the roms. The second method is used by the driver of hard disks. 
Again in the start code, a special routine is called to scan all possible SCSI address for 
hard disks. If a hard disk is found, the start code reads a driver from the hard disk and 
installs it into the I/O system. The final method of installing drivers is to have special 
‘init' or application which installs the driver into the system. Examples of this method 
could be easily found in the case of CD rom, Laserwriter SC, Scanner, and the tape disk 
product. 


2. Introduction 
The SCSI Rover is targeted to solve/ease the process of installing drivers for SCSI 
devices. The SCSI rover will be a general tool used to dynamically bind a driver to a 
device on the SCSI bus. Driver files(in the system folder) , which follow a predefine 
structure, will given the opportunity to install itself if its hardware counterpart is found 
on the SCSI bus. Rover removes the need for separate init's such as the one used by 
the CD Rom, Scanner, and possibly the Laserwriter SC (??). 


In solving this problem, the current method of initializing hard disk can be migrated to 
PACK2, the same method used by floppy disks. 


3. Interfaces 
3.1. User Interface 


The rover is a background task with no user interface. 


3.2. Software Interface 
The software interface consist of files which follow the Rover format. The files 
must have the following to function correctly with the rover: 


(possibly 


(possibly 'scdr'’) 
R resource with a 


eresesesesecaesceraneiers 


‘Unit 


Ta 


ble 
id's Used 
fee Ne Satin lan aa ak Ts al 
bei counters ie SCSI devices 
Known devices | 
SCSI 
ROVER 
inquire possible addresses 
Look for 
driver file with 
id string matching 


inquire response 


Resource Map 


cin{peripherial] 
- install code 


Estr[peripheral] 
- id string 


4. Description 


The rover is responsible for performing a very specific task. It is to search the bus 
periodically for new devices. When a new device is detected, the rover will then search 


for the corresponding driver file in the system folder. The rover will read and execute 

the installation code of that driver file. These three simple action comprise the entire 

function of the rover. By design, the rover could be used by anybody who supplies a 

driver file which conforms to the minimum requirements of a standard rover driver file. 

4.1. Scan 
The SCSI rover is targeted to allow the dynamic "binding" of a driver to a SCSI 
device. The soul purpose of the ROVER is to "scan" unused SCSI address 
looking for possible new devices. SCSI address will be considered unused if the 
unit table entry associated with the SCSI address is NULL. The unit table is used 
to make this determination since it is the only data structure in the Mac which 
provides a one-to-one mapping between device address and all recognized devices. 
To determine the existence of a new device, the rover ‘blindly’ send a SCSI 
‘inquire" command to the unused addresses. If no device exists, the SCSI 
command will fail. Otherwise, identification information will be obtained from the 
new device. This information will be used as a key in determining the correct 
driver to link. All Apple approved SCSI peripherals currently implement the SCSI 
Inquire command which returns the id string and the peripheral type 
4.2. Find A Driver 

With the information gained from the ‘scanning’ operation, the rover will search 
the system file for the correct driver to link. The id information returned from the 
scanning is compared to id information stored in each driver file. Determination of 
which driver file to use is done on the basis of the SCSI id string and peripheral 
typeteturned from e néw device —A.snecia ing i 
easter driver binding beqween ajdriver and a multi sourcdd peripheral. If the 
special ID is used, thenjthe burflen of correct binding is placed on the drivers 


contained mgfule vhhich knows how to install the 


5. Implementation 
| The SCSI rover could have been implemented in four possible locations, a VBL task, a 

Time Manager task, a Deferred Task, and a driver/DA which needed periodic time. The 
SCSI rover is implemented as a driver with the needstime field set to the interval 
between scans on the bus. The reason for making the rover a driver is driven by the fact 
that the rover will have to allocate memory. This ability is needed to bring in drivers 
into the system heap. The other three possible implementations would run at interrupt 
time not allowing memory management calls. 


A final possibility is to make the rover a ‘patch’ to system task. This possibility is still 
under consideration. 

5.1. Open 
The open routine for the rover will initialize the array counters which indicated the 
ids the rover attempted to bind drivers to. (NOTE: the array counters are used to 
restrict the number of attempts to bind a driver to a device) 

5.2. Control 
The control call is the heart of the rover. The rover will ignore all control calls 
except the "accRun" code. This will be the calling code which will trigger the 
rover to scan the bus for new devices. The rover will then poll addresses which 
are considered unused. Both the unit table and a array counters of "SCSI 
addresses attempted" will be consulted to determine addresses to poll. 


All unused address are polled for possible new devices. A SCSI "inquire" 
command will be sent "blindly" to the address in an attempt to determine the type 
of device. If an error occurs, it is assumed that no device is at that address or the 
device is not ready. If no error occurs, a string ID and peripheral type will be 
obtained from the device. This information will be used to determine which driver 
file to use when linking a driver to the device. 


Based off the information obtained from the Get ID call, this routine will search 
through possible driver files in the system folder. Driver files which are used by 
the rover will have a unique ID as the creator. This allows for first level filtering 
of non driver files. The ROVER will then check driver file candidates to see if it is 
the right driver file. This determination is made by looking : in the #STR resource 
of the driver file. The peripheral type return from the "inquire" command is used 
to determine which resource in #STR to look. If a string match is found then the 
driver file is determined to be highly likely candidate. Its install code is brought in 
and executed. If the return value from the install code is zero, we have found our 
driver and it is installed. If it comes back non-zero, then the search for a driver file 
continues until the files are exhausted. If a driver is not found, the ROVER will 
take no farther 


5.3. Status 


Not implemented. 


5.4. Prime 
Not implemente 


the rover run cCOltieHtexsty After power up", Or shou 4 the Rover only run for a 
period of time after power up and then shut itself down. 


Running continuously will promote user power cycling and connection changes 
DURING a power up situation. Although this is generally done with success, 
failures can be induced by these actions. Failures include destroying hardware 
driver circuits. Running continuously will provide the user with the ability to 
mount hard disk drives after power up. Currently either Paul Mercer's DA is 
used, or power cycling of the machine is required. This benefit will probably not 
be utilized by a majority of the current Macintosh users. (I could be wrong!) 
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Introduction 


The slot manager is being patched to support 32 bit quickdraw,video cards which need to be addressed in 32 bit 
mode, and video cards with configurable modes. External changes are four new routines added to the slot 
manager: _SecondarylInit, _sSetsRsrcState, _sInsertSRTRec, and _sVersion. Internally, the entire slot manager 
is being patched out with a new substantially re-written version. All the slot manager internal data structures 
have been changed to allow dynamic space allocation for addition of slot resources. All old slot manager calls 
will be supported other than those used only for initialization (they will be unavailable). Incorporated 
within this patch is also support for Mac II 1.0 ROM's which would only address NuBus in 24 bit mode. The 
NuBus slots will be re-scanned in 32 bit mode, and any additional cards seen will be added to the slot manager's 
data structures. 


Patch Installation 


ptch=35 code does nothing more fhan to Joad the othertwo reg os-inte-the-application’s heap: 'slot'=0, the 
patch code, and 'slot'=1, the install ahd initialization code. 


anager intePxal data sttuctures into theApplicgtion's heap. It then disposes 


are not re-inventoried. This means thattrvard's Primarylnit originally deleted sResources, they are not re- 
added to the internal slot resource table. Any vendor information modified in the original slot manager data 
structures is copied to the new data structures. At the end of the slot manager initialization, SecondaryInit 


records are executed and any new video sResources are added to the gDevice list. 


Modified Slot Manager Parameter Block 


The current spBlock used by all slot manager calls is being modified slightly. The field spStackPtr is renamed 
to spParamData. It remains a long. The purpose of the field is for general input and output parameter passing. 


Modified Trap Calling Convention 


The current slot manager trap is an OS trap with the trap word being $A06E. The optional bit flags in the trap 
word will be used to differentiate between slot manager calls which use the old parameter block, and slot 
manager calls which use the new parameter block. 
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New Calls 


All new slot manager calls continue to support the assembly language calling conventions spelled out in Inside 
Macintosh Vol. 5. On entry, register AO contains a pointer to an spBlock. On exit, the low order word of register 
DO contains the status result. 


Trap Macro: _sVersion selector $08 

Required Parameters ->  spsPointer 
-> spParamData (formerly spStackPtr) 
-> spResult 


Return the version number of the slot manager in spResult. spsPointer and spParamData are set to NIL, but may 
in the future return additional information. The version number is meant to indicate a functional level. The 
patched slot manager for 32 bit QuickDraw féturn version 2. Old versions of the slot manager do not have 
this call implemented, and |will return call status error -3$8 (smSelOOBErr - selectoy out of bounds error). 


Required Parameters 


Set the state of an sResource as enabled or disabled. The sResource is identified by spSlot, spId, and spExtDev. 
The state of the sResource is determined by the value of spParamData: 0 = enable,1 = disable. spResult will 
return the status of the call. 


A disabled sResource will not be found by any slot manager routines unless a flag bit in spParamData is set (yet 
to be defined) indicated to these routines to search for disabled sResources.. Otherwise, disabled sResources are 
ignored by the slot manager. This feature allows sResources to be ignored by the slot manager, but still be 
remembered and enumerated later. An application or driver controlling a card with selectable modes, might 
want to enable only the sResource applicable to the current mode, but still be able to list all available 

(i.e. disabled) modes. 


Other routines in the slot manager affected by this feature are: _sRsrcInfo, _sNextsRsrc, _sNextTypesRsrc, 


_sReadDrvrName, _sDeleteSRT, _sSearchSRT, sUpdateSRT, _sGetDriver, _sFindsRsrcPtr, and 
_sInsertSRTRec. These routine will accept the flag indicating whether to search for disabled sResources. 
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Trap Macro: _sInsertSRTRec selector $0A 


Required Parameters ->  spSlot 
| ->  spld 
->  spExtDev 
->  spsPointer 
->  spRefNum 


-> spParamData poe spStackPtr) 
<- — spResult 


This routine adds the sResource identified by spSlot, spId, and spExtDev, to the slot resource table. If 
spsPointer is NIL, and the sResource is found in the spSlot's declaration ROM, then the ROM sResource is 
added. If the sResource identified is not found, then an error is returned in spResult. If spsPointer is not NIL, 
then it is assumed to contain the address of an sResource, and it is added. The state of the sResource may be 
determined by the value of spParamData: 0 = enable,1 = disable. If spRefNum is not NIL, and contains a valid 
driver reference number, then that reference nner will be associated with the siiichabae and the dCtlSlotld, 
dCtlExtDev, and dCtIDevBase fields in the : epdated. spResult will 


This call allows previously deleted aurces to be addéd into the slofresoprce table. New 
sResources may be sResources in 4 card 6t appgar in the sResource 
directory, or sResources defined if RAD appear in a different gard's slot space are not 


Trap Macro: _sSecondaryInit 
Required Parameters ed 


This routine is internal to the slot manager and should never be called by anyone other than the slot manager. 
It invokes execution of SecondarylInit records in board sResource lists. spFlags is passed to the SecondaryInit 
code via seFlags in the sExec parameter block. Within that byte, the fWarmStart bit (bit 2) will be set to 1 if a 
warm start is being performed. No errors are returned. 


SecondarylInit records in the board sResource list have the same format as PrimarylInit records. They are code 
blocks which are executed after patches are loaded, and with interrupts enabled. 
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Introduction 


The Modern Victorian architecture, and Four Square and F19 implementations, contains two Input 
Output Processors (IOPs), formerly called Peripheral Interface Controllers (PICs) which are 
programmable input / output processors that have a shared memory interface with the main CPU 
(68030). By off loading some of the input / output tasks to the IOPs, the main CPU will have more 
free cycles and better performance in a multitasking environment. This document will describe the 
method of passing messages between the main CPU and the IOPs, and other IOP related functions. 
Specific information about how certain drivers interpret the contents of these messages are covered in 
separate documents. Much of the information in this document is very technical and detailed, and is 
provided for mainly for those people who will be writing and debugging drivers on the IOPs. This 
document will also serve as the design specification for the IOP Manager. 


IOP cannot directly 2 any of ff 
that allow the 680 ~L nh Single jnterrupt on each JOP, and each IOP can generate two 
different interrupts on the 6 fU projects, one IOP will be connected 
to a SWIM disk interface chip. TMi fill containfhe codg to support the SONY Driver, and the 
Apple Desktop Bus (ADB) D gther IOP wil} be conrfected to the SCC chip, and will contain 
code to support the Serf etd the Apple Talie-Brivers. The existing 680XX SONY, Serial, 
and Apple Talk Drivers will be modified to communicate with the driver code on the IOPs, by using 
calls to the IOP Manager, instead of directly accessing the SWIM or SCC controller chips. The IOP 
Manager provides sufficient functionality such that code outside of the IOP Manager should never need 
to directly access the IOPs. 


@SS 


iOP_ Numbering 


The IOP Manager data structures are designed to handle multiple IOPs, and an upper limit of eight 
IOPs per system has been set. IOPs are numbered from zero to seven, with zero and one assigned to 
the SCC and SWIM IOPs respectively. The remaining IOP numbers are available for future 
expansion, and the possibility of IOPs on add on NuBus cards. The following constants are defined 
for referring to the IOPs. 


CONST 
SccIopNum = 0; {SCC IOP is number 0} 
SwimIopNum aes Oars {SWIM IOP is number 1} 
MaxIopNum = 7; {8 IOPs supported, numbered 0..7} 
NumberOfIOPs = MaxIopNum+1; 
IOP Manager ERS Rev 1.0 Al 1 January 18, 1989 
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Accessing IOP Memory Data 


A routine is provided to copy data to and from a IOP memory, or compare HOST memory with IOP 
memory. Additionally it provides a special mode to allow a series of patches to be applied to IOP 
memory as an atomic operation (during which time, all other processing on the main CPU and on the 
IOP being patched will cease), in which case imHostAddr is passed a pointer to a series of packets, 
terminated by a zero length packet, that have the same format as the contents of an initial IOP code 
image resource, and the imByteCount and imlopAdadr fields are ignored. To copy IOP data, the 
__I0PMoveData trap should be called with parameters passed as follows. 


CONST 
{imCopyKind encodings} 
imIopToHost = 0; {Copy from IOP to main CPU} 
imHostTolop = 1; {Copy from main CPU to IOP} 
imCompare = 2; {Compare Host memory with IOP memory} 
imPatchIop = 93; {Patch IOP memory} 
TYPE IOPMoveInfo = 
RECORD 
imCopyKind: SignedByte; nd/direction of copy} 
imIOPNumber: SinGHe-cs IOP Numb 3 5 ait 
imByteCount: Integer; {Count of (except PatchIop) } 
imHostAddr: Ptr; Hgst CPY memg 
imIopAddr: {IOP mempryfaddress (efcepy PatchIop) } 
imCompRel: - | Sidpe ; Pace = HOST, 
INif IOP > HOST 
imReserved: d, Reserved 
END; 


Trap Name: _IOPMdveDa 
On Entry: 
AO Address of IoPMoveInfo record 
On Exit: 


DO result code as follows 
NoErr Operation was successful. 
ParamErr Operation was unsuccessful for one of the following reasons. 
imCopyKind is out of range. 
imIOPNumber is out of range. 
The specified IOP does not exist, or is not initialized. 


Message Passing in General 


The IOP Manager provides an asynchronous message passing mechanism to allow tasks on the Host 
and IOP processors to communicate with each other. Message transactions may be initiated by either 
the Host or the IOP processor. There can be as many as seven message transactions occurring 
concurrently in each direction (for a total of 14 messages per IOP). The message data can be up to 32 
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- bytes in length, and its contents is not dictated by the IOP manager. The message format, as well as 
the message number, is agreed upon by the sender and receiver of the message. 


A message transaction actually consists of four phases. In the first phase, the transmitting processor 
copies the Message into a shared memory message buffer, and notifies the receiving processor that a 
message has been sent. In the second phase, the receiving processor will read the message and take 
whatever action is necessary to process it. In the third phase, the receiving processor will write a reply 
message into then shared memory message buffer, and then notify the transmitting processor that the 
message processing is complete. Finally in the fourth phase, the transmitting processor will copy the 
reply from the shared memory message buffer, and indicate that the transaction is complete, and call 
the completion handler associated with sender of the message. 


The IOPMsgRequest trap is provided to handle all message passing operations. 


CONST 
MaxIopMsgNum = 7; {Message numbers range 1..7} 
MaxIopMsgLen = 32; {Message length range is 0..32 bytes} 
{irRequestKind encodings} 
irSendxXmtMessage = 0; {Send Transmit megs Read reply when done} 
irSendRcvReply : Send Re for next Receive Msg} 
wait 


irWaitRcvMessape = 2; 


irRemoveRcvWaiter remove wait for receive message request} 


TYPE IOPRequest Info 


RECORD 
irQLink: Pur; {Peinter to ne quefe element } 
irQType: ue Element/ type 
irIOPNumber; Number 
irRequest : Bi ae ie ropa megeace equest to perform} 
irMsgNumbetr : 5 i ; essage n . .MaxIopMsgNum) } 
irMessageLex: Message Bp ngth (0..MaxIopMsgLen) } 
irReplyLen: e; {Reply Buf gth (0..MaxIopMsgLen) } 
irRegActive: SignedByte; {SFF when active, or queued, $00 when completed} 
irMessagePtr: Ptr; {Message buffer address} 
irReplyPtr: PCr; {Reply buffer address} 
irHandler: _ ProcPtr; {Completion handler procedure address} 
END ; 


Trap Name: _IOPMsgRequest ($A087) 
On Entry: 
AO Address of IOPRequestInfo record 
On Exit: 
DO result code as follows 

NoErr Operation was successful. 


ParamErr Operation was unsuccessful for one of the following reasons. 
irRequestKind Is out of range. 
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irlOPNumber is out of range. 

The specified IOP does not exist, or is not initialized. 
irMsgNumber is out of range, or not supported by this IOP. 
irMessageLen is out of range. 

irReplyLen is out of range. 

irSendRcvReply when another receiver already exists. 
irSendRcvRep1y while request is still active. 
irWaitRcvMessage when another receiver already exists. 
irRemoveRcvWaiter when no receive waiter exists. 


Host _ Initiated Message Passing Transactions 


To send a message from the Host to the IOP, the IOPMsgRequest trap is used with the 
IOPRequest Info parameter block setup as follows. 


irRequestKind should be set to irSendxmtMessage. 


irIOPNumber and irMsgNumber should be-set to indicate the receiver of the message. 


irMessagePtr should pqint to the eee data to Ye 
the length of the message qatar iy 
needed, in which case irM 


sent, and irMessag¢ en should indicate 
hott 2 2 


indicate the length of the rep buffer (Which mal be zero if 9 reply is expected, in which case 
irReplyPtr is not used). 


be set to zero if no handler 1\ 


When the . IOPMsgRequest is made with the parameters described above, the following operations 
occur. The parameters are checked for validity, returning with an error if invalid. The request is now 
marked as being active (irReqAct ive will be set to $FF). The new request will be placed at the end 
of the transmit message queue associated with this message. If there was already an active request in 
progress for this message (the new request is not at the head of the queue), it will return now, with 
NoErr, and the request will be processed when the request ahead of it completes. 


The first phase of the message transaction now begins, by copying irMessageLen bytes of 
message data pointed to by irMessagePtr, into the shared memory message buffer in IOP 
memory. A message state byte is also updated to indicate that a new message has been sent, and the 
Host processor will interrupt the IOP to notify it that a message needs processing. This trap will now 
return with NoErr indicating that the request processing has started. 


The IOP will now go through the second and third phases of the message transaction, while the Host 
processor is free to proceed with other processing. At the end of the third phase, the IOP will interrupt 
the Host to notify it that a transmit message has completed. 


The Host interrupt handler will process the fourth phase of the transaction, by searching the message 
states to find which message has completed, and then locate and de-queue the TOPRequest Info 
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parameter block at the head of the queue for that message. It will copy irReplyLen bytes of the 
reply from the shared memory message buffer in IOP memory to the buffer pointed to by 
irReplyPtr. The message state byte is also updated to indicate that a reply has been received. The 
completed request will be added to a queue of completed requests that will be processed by a deferred 
task which will run after all other interrupt processing has completed. 


If there were any other message requests queued up for this message, the request at the head of the 
queue will be initiated now. 


Finally the deferred task will run, still at interrupt stack level, but with interrupt priority lowered to 
zero, So all the rules about causing heap moves, and use of unlocked handles, etc. still apply. It will 
go through each entry in its completion queue, de-queuing it from the queue, setting irReqActive 
to $00 to indicate that the request is complete, and will call the procedure pointed to by irHandler, 
unless the pointer is zero. Register AO will point to the [OPRequestiInfo parameter block 
associated with this request, which will allow the handler to find its private storage (by appending or 
prepending additional data to the parameter block, or by embedding the parameter block within the 
private storage, and address other data relative to the parameter block). The handler, like most other 
Macintosh interrupt handlers, may destroy registers AO-A3, and DO-D3, and must preserve all other 
State. 


Due to the ener Ya ature 13 ea$h etakento be sure that the pointers 
Tnfo record itself, point to 
of the stack that might be 


For the first required call, TxR@questKind should be set to irbWaitRcvMessage. This call is 
used to install a handler to receive messages initiated by the IOP. 


irIOPNumber and irMsgNumber should be set to indicate the sender of the message. 


ixrMessagePtr should point to the message buffer to receive the message, and irMessageLen 
should indicate the length of the message buffer (which may be zero in the unlikely case when no 
message data is needed, in which case irMessagePtr is not used). 


irHandler should point to the procedure to be called when the IOP sends the message, or should be 
set to zero if no handler is needed. 


When the IOPMsgRequest is made with the parameters described above, the following operations 
occur. The parameters are checked for validity, returning with an error if invalid. If there was already 
a handler installed to receive this message, ParamErr is returned. Otherwise, the request is now 
marked as being active (irReqActive will be set to SFF). The request will be installed as the 
receive message handler associated with this message, and it will return now, with NoErr. 


When the IOP wants to send a message, it will initiate the first phase of the message transaction by 
copying the message into the shared memory message buffer in IOP memory. The message state byte 
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is also updated to indicate that a new message has been sent, and the IOP processor will interrupt the 
Host to notify it that a message needs processing. 


The Host processor will now go through the second phase of the message transaction, while the IOP is 
free to proceed with other processing. The Host interrupt handler will process the second phase of the 
transaction, by searching the message states to find which message has completed, and then locating 
the L[OPRequest Info parameter block associated with that message. It will copy irMessageLen 
bytes of the message from the shared memory message buffer in IOP memory to the buffer pointed to 
by irMessagePtr. The message state byte is also updated to indicate that a message has been 
received. The request will be added to a queue of requests that will be processed ioe a deferred task 
which will run after all other interrupt processing has completed. 


Finally the deferred task will run, still at interrupt stack level, but with interrupt priority lowered to 
zero, So all the rules about causing heap moves, and use of unlocked handles, etc. still apply. It will 
go through each entry in its queue, de-queuing it from the queue, setting irReqActive to $00 to 
indicate that the request is complete, and will call the procedure pointed to by irHandler, unless the 
pointer is zero. Register AO will point to the TOPRequest Info parameter block associated with this 
request, which will allow the handler to find its private storage (by appending or prepending additional 
data to the parameter block, or by embedding the parameter block within the private storage, and 
address other data relative to the Parameter bjeck). The handler, like 1 most other Macintosh interrupt 


The second required call ig 
message back to the IOP, 


send the reply, with irRequestKind modified to be i senan Rec If the request is still 
marked as being active (ie. waiting for the IOP message), ParamErr will be returned. 


irReplyPtr should point to the buffer to send as the reply to the IOP, and irReplyLen should 
indicate the length of the reply buffer (which may be zero if no reply data is needed, in which case 
irReplyPtr is not used). 


The Host processor will now enter the third phase of the message transaction, by copying the reply 
message into the shared memory message buffer, and updating the message state to indicate that the 
message is completed. The Host will now interrupt the IOP to notify it that a message has completed. 


The Host processor will now again prepare to receive messages initiated by the IOP, by repeating the 


same operations as above when irRequestKind was set to irWaitRcvMessage. 


The third call, which, depending upon the situation, may or may not be needed, is used to remove a 
receive message handler. 


The same IOPRequest Info parameter block that was used to wait for the message must be used to 
remove the handler, with irRequestKind modified to be irRemoveRcvWaiter. otherwise 
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ParamErr will be returned. If the request will marked as being complete, and there will no longer be 
a handler associated with that message. 


1OP_ Installation and Removal 

The IOP Manager provides an interface that allows IOPs to be dynamically added and removed. This 
routine would most likely be used to install an IOP that resides on some sort of expansion card, 
although it is called internally by the IOP Manager initialization routine at system startup time to install 


the two currently defined IOPs. The following data structures and calls are used to install, remove, 
and access the information about an IOP. 


TYPE IOPMsgEntry = 


RECORD 
RevMsginfoPtr: Ptr; {Ptr to rev msg handler info (IOPRequestInfo) } 
Reserved: Word; {unused, reserved} 
XmtMsgQHdr: QHdr; {queue of transmit requests (IOPRequestInfo) } 
END; 


TYPE IOPInfo = 


RECORD 
IopAddrReg#tr: : {Pt?¥e to IOP RAM Addres$ Reg (word) } 
IopDataReg#tr: {P gg (byte) } 
IopCtlRegPitr: E ; {Per Yo IOP Contyol Keg (byte) } 
BypassHand]Jer; E { errApt Handler Address} 
MaxXmt : {Highest Tra essage number} 
MaxRcv: {Highest Regeive fmessage number} 
Reserved: {unused, - 


MoveReqIinfo: 
MoveReqBuffer: 


MsgTable: of IOP ; {message handler info} 
END; 
CONST 
iaInstallIop = 0; 
laGetIOPInfo = 1; 
iaRemovelI0OP = 2; 


TYPE TOPAccessInfo = 


RECORD 
iaAccessKind: SignedByte; {kind of request to perform} 
iaIOPNumber: SignedByte; {IOP Number (0..MaxIopNum) } 
Reserved: Word; {unused, Reserved} 
ilaIOPInfoPtr: Ptr; {pointer to IOPInfoRecord} 
END; 


Trap Name: IOPInfoAccess ($A086) 


On Entry: 
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AO Address of IOPAccessInfo record 
On Exit: 


DO result code as follows 
NoErr Operation was successful. 
ParamErr Operation was unsuccessful for one of the following reasons. 
iaAccessKind Is out of range. 
iaIOPNumber is out of range. 


When iaAccessKind iS iaInstall1Iop, the following are possible 
ialOPNumber already exists. 

The 'iopc' resource for ialOPNumber could not be found. 
iaIOPNumber failed its RAM test, or failed to initialize. 


Associated with each installed IOP, there is an IOP Info record. It contains the information needed 
by the IOP manager to process requests for that IOP. IopAddrRegPtr is a pointer to the 16 bit IOP 
RAM Address register, pelea eee ae to the 8 bit IOP RAM Data register, and 
IopCtlRegPtr is a pointarte-th : OF pesspHandler is a pointer 


to the interrupt handler to He at the Host, and the IOP was in bypass 
mode. MaxXmt and MaxRav are : i SHA bSE-St e4 by the IOP in each 
direction. MoveReqinf¢q e IOP requested data 


An IOPMsgEntry record contains the infd angmit and receive messages for 
a given message number IOPR¢quest Info record which is 
the receive request ass tMsgQHdr is a queue of 
TOPRequest Info record =m pe is the trarfsmit mefsage that is currently active for 


this message number. 


The IOPAccessInfo record is used with the IOPInfoAccess trap to access or change 
information associated with a given IOP. iaAccessKind describes the operation to perform, 
iaIOPNumber is the IOP to operate upon, and iaIOPInfoPtr is a pointer to an LOP Info record 
that is either passed in, or returned, depending upon the operation. 


When iaAccessKind set to iaGet IOPInfo, ialOPInfoPtr will be returned with the pointer 
to the IOP Info, or will be zero if there is no IOP Info for that IOP. 


When iaAccessKind set to iaRemovelIOP, the IOPInfo for the specified IOP will be removed, 
and a pointer to it will be returned in iaIOPInfoPtr. 


To install a new IOP, iaAccessKind is set to iaInstallIOP, and ialOPInfoPtr should 
point to the LTOPInfoRecord for this IOP. The TopAddrRegPtr, IopDataRegPtr, 
IopCtlRegPtr, and BypassHandler pointers in the IOP Info record must be setup prior to 
making the IOPInfoAccess trap. The IOP will be installed, and initialized as follows. 


Since a IOP doesn't have any ROM, it will execute code out of part of its 32K bytes of RAM. The 
main CPU ROM will contain the code for each IOP, usually stored as a ROM resource. 
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_RGetResource is used to locate the resource, so that is may be overridden by a resource in another 
resource file. If the resource is not found at all, paramErr will be returned. The ResType is 
'Lopc' and theID corresponds to the IOP number. The IOP Code resource will be organized as a 
sequence of variable length packets, terminated by a zero length packet. A packet will have a three 
byte header followed by 0..255 bytes of data. The first byte of the header contains the length of the 
packet data. The remaining 2 bytes of the header contains the IOP memory starting address where the 
data from this packet should be placed. When the code gets loaded into IOP memory, any bytes that 
were not loaded will be set to zero. This should allow a significant saving in the size of the IOP code 
resource, since long strings of zero bytes (3 or more), can be compressed out of the load image. 


The Host CPU initializes the IOP hardware by first putting the IOP into the RESET state, which 
prevents it from executing instructions. It will then write a pattern of $FF to each byte in IOP 
memory. It will then read each byte of IOP memory, checking it to make sure that it was written as 
$FF, and replace it with a value of $00. Next it will check all of IOP memory to make sure that it was 
correctly set to zeros. Finally, the IOP code will be loaded, and read back to verify that it was loaded 
correctly, and the main CPU will put the IOP into the RUN state, to allow it to start executing the now 
loaded IOP code. The Host CPU will wait for the IOP to finish executing its initialization code, and 
then install the Move Message Request handler which will be described later. If any of these 
operations fail or timeout, it will be considered a fatal hardware failure for that IOP, and any future 
calls to the IOP Manager to communicate with the faulty IOP will return an error status indicating that 
that IOP does not exist, 


Move Reque deve Message Ha 


d ess the main CPU memory, it is 
necessary for some IDP based drixers to da\so. This is achjéved by having the IOP send a message to 
the main CPU requestimg it to copy the data to or from theAOP mémory. IOP to Host receive message 
number one will be ya brt this operftion. Yhe IOP Manager provides and installs 
a handler for this nf ’s in the sytem, td perform the data movement requests. 

The format of the messag& that j4e IOP sfnds is the fame fofmat as the IOPMoveInfo parameter 
block used by the OPMoveDat aftrap, with tHe exception that the IOP does not fill in the 
imIOPNumber field. —~Wher-thH€ Host receives The message from the IOP, it will fill in the 
imIOPNumber field with ihe correct IOP number, and call the IOPMoveData routine to process 
the move request. When the move completes, it will send the IOPMoveInfo parameter block back to 
the IOP as the reply message, and wait for the next move request. There are currently no assigned 
functions for Host to IOP transmit message number one. 


Initialization 


Early in the booting process (before any drivers are opened) the StartManager will call the IOP 
manager routine Init IOPMgr which will create the IOP Manager global data structures in the system 
heap, and make IOPInfoAccess calls to install and initialize the IOP hardware for the two 
currently defined IOPs. Additionally, it will start up a VBL task that will monitor the IOPs every few 
seconds to see that they are still alive. This is a debugging aid, and will not be part of the final 
production version of the IOP Manager. 


The globals data structures used by the IOP Manager are as follows. Note that IOPmgrVars does not 
point to the beginning of the record, instead it points to the TOP InfoPtrs field of the record, so that 
this data structure may expand in both directions in the future. 
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CONST 


IOoPmgrVars = $0C28; {low mem Ptr to IOPInfoPtrs field of 
ITOPMgrGlobals record} 
TYPE IOPMgrGlobals = 


RECORD 
Fillerl: Word; {force nice long word alignments} 
vTask: VBLTask; {IOP polling task} 
DTask: DeferredTask; {completion caller deferred task} 
Filler2: SignedByte; {unused, reserved} 
DTaskQueued: SignedByte; {-1 if task queued or running, 0 when done} 
CompleteQHdr: QHdr; {queue of completed requests} 
IntHandlerPtr: ProcPtr; {pointer to IOP Interrupt handler} 


{IOPmgrVars points here} 


IOPInfoPtrs: Array [0..MaxIopNum] of Ptr; 
{Ptrs to IOPInfo records for each IOP} 
SCCIOPInfo: IOPIinfo; {info for IOP 0 (SCC) } 
SWIMIOPInfo: IOPInfo; {info for IOP 1 (SWIM) } 
END; 


afid the transition order 
without the need for 


afd no action is needed by the 
g¥ processor that this message is 


state ates esspr that the message data is now 
valid, and that it may now receive it, and start processing it. The sending processor also interrupts 
the receiving processor to indicate that there is a message that is now in this state. The receiving 
processor now owns the message data, and the sending processor can no longer modify it. This 
state is only set by the sending processor. 


¢ Message Received — When the receiving processor has received a message, and has started 
processing it, the message state changes to this state, to acknowledge the the interrupt, and to 
indicate that it has started processing the request. This state is only set by the receiving processor. 


¢ Message Completed — This state indicates to the sending processor that the receiving processor has 
completed processing the message, and any returned message data is now valid. The receiving 
processor also interrupts the sending processor to indicate that there is a message that is now in this 
state. The sending processor now owns the message data, and the receiving processor can no 
longer modify it. This state is only set by the receiving processor. 


¢ Idle — When the sending processor has acknowledged the message completed interrupt for the 
message, and processed any message data that was passed back by the receiving processor, it 
changes the message state to /dle to release the message. This state is only set by the sending 
processor. 
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While the desired order of state transitions is the order listed above, it may be desirable for some driver 
implementations to skip some state transitions. It is allowable to transition directly from New Message 
Sent to Message Completed without going through Message Received. It is also allowable to 
transition directly from Message Completed to New Message Sent without going through /dle. 


The message state will occupy 1 byte for each message, the encodings are as follows. 


CONST 
Msgidle = 0; {message buffer idle} 
NewMsgSent = 1; {new message just sent} 
MsgReceived = 2; {message received, and being processed} 
MsgCompleted = 3; {message processing complete, reply available} 


har Memory Data Structure 


The 65CX02 organizes its memory into pages of 256 bytes. Page zero is used by special addressing 
modes, and page one is used for the 65CX02 stack. We will allocate a total of two pages (pages 2 and 
3) of shared memory for message passing, where the first page (page 2) will be used for messages 
sent from the main CPU to the IOP, and the second page (page 3) will be used for messages sent from 
the IOP to the main CPU. The layout of €ach of these pages will be as follows. 


Aumber used by this IOP. — 


$01 1 ge Stat& for message 1 
$02 1 age State|for megsage 2 
$06 1 for m@ssage 6 
$07 1 essage 7 
$08 24 Reserved 

$20 32 Message Data for message 1 

$40 32 Message Data for message 2 
$CO 32 Message Data for message 6 
$EO0 32 Message Data for message 7 


In addition to the message passing, there are two special bytes in IOP memory (IOP addresses $021F 
and $031F) which are used as follows. 


IOP memory address $021F will be used to synchronize patching of code in a running IOP. When a 
IOP is otherwise idle, it will check this byte, and if it contains the value New Message Sent , it will 
disable all interrupts, and change the value of this byte to Message Completed, and then wait in a loop 
(with interrupts still disabled) waiting for the value in this byte to change to /dle. It will finally 
re-enable interrupts, and continue with its idle loop. When the IOP Manager wants to patch code in a 
running IOP, it will disable all interrupts, and store the value New Message Sent into this patching 
flag byte in IOP memory, then it will poll the byte, waiting for the value to change, at which time it 
will know that the IOP is in a state ready to be patched. The IOP Manager will then apply the patches, 
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and finally store the value Jdle into the patching flag byte, and re-enable interrupts. 


IOP memory address $031F will be used to allow the main CPU to check to see if a IOP is still alive (it 
may have hung or crashed, due to hardware or software problems). The IOPs will store $FF into this 
alive flag byte when it is otherwise idle. The VBL task in the IOP manager will read this byte, and 
clear it, every few seconds to make sure that the IOPs are still alive 


interr 


When the Host processor detects an interrupt from an IOP, it needs to call the IOP Manager's interrupt 
handler routine, and pass the interrupting IOPs number in the low word of register DO, and flags 
indicating which messages completion routine must run immediately, and which ones can be deferred 
in the upper 2 bytes. The highest byte refers to Host to IOP message completions, and the next byte 
refers to IOP to Host message requests. Each bit of the byte is associated with the corresponding 
message number, and a zero bit indicates that the completion routine can be deferred, while a one 
indicates that it must be run immediately. This allows message processing to proceed in an 
environment (like the keyboard polling code for MacsBug) where interrupts are disabled (which 
prevents deferred tasks from running), and the IOP interrupts are polled, and the interrupt handler is 
called to service the request, without ever enabling interrupts. The address of the interrupt handler 


implementation 


The IOP Manager is being implemented in MPW 68020 assembly code (using newer addressing 
modes and opcodes where appropriate). It is expected to use less than 1.5K bytes of ROM space, and 
less than 500 bytes of RAM space in the system heap to support the two currently defined IOPs. 


IOP Manager ERS Rev 1.0 Al 12 January 18, 1989 
Apple Computer Confidential 


IOP SWIM Driver ERS 


Gary Davidian 
ext. 4-4510 
MS 27-AJ 
Rev. 1.0 D1 1/18/89 


Introduction 


The Modern Victorian architecture, and Four Square and F19 implementations, contains two Input 
Output Processors (IOPs), formerly called Peripheral Interface Controllers (PICs) which are 
programmable input / output processors that have a shared memory interface with the main CPU 
(68030). By off loading some of the input / output tasks to the IOPs, the main CPU will have more 
free cycles and better performance in a multitasking environment. On the current IOP based CPU 
projects, one IOP will be connected to a SWIM disk interface chip. This IOP will contain the code to 
support the SONY Driver, which supports all disk devices that can be connected to the SWIM chip. 
The basic message passing protocol between the Main CPU and the IOP is described in the JOP 
Manager ERS document. This document will describe the format of the messages used to 
communicate with the IOP based disk driver. Since the existence of IOP Manager is model dependent, 
and given that no user written code spout#l ever execute on this IOP, or need to call the IOP Manager, 
the information in thfs document should rot be dpcumented outside of Apple Computer, specifically, I 
h. 


The SONY Driver forSy , 
IIx SONY Driver (ipehdi ) disk drjve support but wfll be modified to pass messages to an 


There is one new feature that is needed to support the Columbo package. Columbo will have a key 
operated switch to lock the system in an unattended server mode. While in this mode, all I/O to the 
floppy drives will be disabled, to prevent tampering with the system. 


The Macintosh IIx SONY Driver allocates its track cache (9K Bytes) in the system heap. On SWIM 
IOP machines, the track cache will reside in IOP RAM, freeing up some system heap space, and may 
be larger (18K Bytes), so that it can cache two tracks (one from each side of the disk). This has both a 
positive and negative performance impact. On the positive side, it frees up 9KB of system heap RAM, 
which can be put to better uses, and it has a larger cache so the chances of a hit in the cache are greater. 
On the negative side, since the cache is managed by, and resides in the IOP, you must pay for all of the 
overhead associated with cross processor message passing and data transfer, even when you hit in the 
cache, but overall, I think that the positives will out weigh the negatives. 


The Macintosh IIx SONY Driver that supports the SWIM chip, uses the TWM half of the SWIM chip 
for all access to GCR disks (400K/800K), and switches the SWIM chip into ISM mode when 
accessing MFM disks (720K/1440K). The IOP SWIM Driver will use ISM mode exclusively, and not 
use IWM mode at all. The reasons for using just the ISM are as follows. Only ISM mode provides 
the hardware handshake signals used by the IOP DMA hardware, the WM has no handshake signal. 
The only way to access the HeadSelect control line from the IOP is through a register in the ISM 
register set, it cannot be accessed in IVM mode. The ISM provides a much nicer interface to software 
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than the IWM, which will make the driver code, faster, smaller, and easier to understand, than if the 
IWM mode were used. Mode switching is not required if only one mode is used, and ISM mode is the 
only mode that will support all of formats and drives that we need to support, IWM mode only 
supports 400K/800K GCR and HD-20. 


There is some risk associated with this decision. No other project has used the GCR capabilities of the 
ISM mode of the SWIM chip within Apple, since prior machines use IWM mode exclusively for GCR 
mode, and just use ISM mode to access MFM encoded disks. However, I understand that the 
consulting firm that designed the ISM has tested, and does use the GCR capabilities of the ISM 
successfully. Additionally, the implementation of the IOP SWIM driver has progressed to the point 
where GCR reads and writes are implemented, and they appear to be working without any problems. 


There is one extension that is being considered if development resources exist, and if it appears to be a 
desirable extension. That extension is the addition of HD-20 (the old slow non-SCSI ones) support. 
Support for the HD-20 was not included in the Mac II ROMs, but was later implemented in a RAM 
based version of the SONY Driver, which along with a special cable (the Mac II does not have an 
external disk connector), or using the built in external floppy connector on the Macintosh SE-30 or 
Cobra I, allowed access to the HD-20 (the intention was to allow users who upgraded to Mac IIs to 
transfer their data off of old HD-20s onto newer SCSI hard disks). If this type of upgrade path is still 
popular, the only way that it could be supported would be through the IOP based driver, it would be 
best to have it implemented in the standard Ariyer, instead of having two drivers. If development 


resources do not exist, then tfiSTéature may not bg implefnen 


Compatibility Impact 


Since the new SONY Driveq and SWIM Driver will implemen exacfly the same functionality as 
the Macintosh IIx SONY Driyg lication \hat runs on te Magintosh IIx, and accesses the 
SONY Driver through the Device Manager should hot have any/compafibility problems with the IOP 
based implementation. 


a 


g £Code could juntpindirest through these RAM locations, 
which could be patched to fix potential bugs in the ROM code. If there are any applications that use 
these patch vectors to directly call these internal SONY Driver routines (or worse yet, to change the 
way these routines work), or access an of the internal data structures of the SONY Driver, they will 
probably not run correctly on SWIM IOP based machines. Inside Macintosh does not document these 
data structures, vectors, or the routines that they point to, so anyone who is doing this is probably also 
doing other sleazy, model dependent things and is asking for trouble. 


Many Copy Protection schemes access the disk in ways other than by accessing the SONY Driver 
through the Device Manager, and may do thing such as patching portions of the SONY Driver, or 
directly accessing the WM hardware. Since the 680XX CPU, or SONY Driver on SWIM IOP based 
machines will not be accessing the disk interface hardware directly, it is to be expected that many 
copy_ protected applications WILL NOT RUN on SWIM _IOP based machines! 


It may be possible to support some copy protected software, if they are just making minor patches to 
the SONY Driver, such as changing the values of Address Marks, or the GCR encoding tables. This 
type of support , if implementable, will not be added until after the driver is fully implemented, and — 
debugged, and we are able to determine which applications might benefit from this type of kludge. I 

feel that this should only be done if there are some very strong business reasons to support it. Another 
approach might be to work with the copy protection developers (and to be fair, the developers of copy 
protection copying/defeating software), to establish a driver interface to accomplish what they need to 
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do, and implementing it in this and all future SONY drivers. 


Pages 2 and 3 of Macintosh Technical Note #2 (May 1986) and pages 21, 24 and 25 of Macintosh 
Technical Note #117 (March 1987) address using undocumented low memory globals, directly 
accessing the hardware, and copy protection. It's not like we haven't been warning developers that 
something like the IOPs might come along someday. 


M Passin verview 


The 680XX based SONY Driver will communicate with the IOP based SWIM Driver using the 
message passing interfaces provided by the IOP Manager. The format and contents of these messages 
is described below. Developers should access the floppy drives by using the File System or the 
SONY Driver, and should NOT communicate directly with the IOP based SWIM driver, just as they 
shouldn't directly access the IWM/SWIM chips on other system. The information below is to be used 
internal to Apple for the Macintosh SONY Driver development, and possibly for the A/UX floppy 
driver development. 


An IOP based driver can receive messages from the main CPU, and will notify the main CPU when 
processing of the message request is completed. It can also return information in the completed 
message. This method will be used foytifg main CPU to request disk operations to be performed. The 


It is also possible fox tver to send rpéssages to the’mayf CPU, which will be used to 
notify the main CP j asjust been iksefted, or manally gjected. The IOP to main CPU 
message number 2 


Additionally, the I[OFSaag€ driver wil request data ove ent between the IOP and main CPU 
memories, using IOP i age number A, as déscribed in the JOP Manager ERS 
document. 

Main PU to IOP “SWIM river Reques inds 


By convention, the first byte of any message associated with the IOP based SWIM driver will be a 
request kind. The request kinds for the main CPU to IOP SWIM driver messages are as follows. The 
error codes returned by these calls are the same error codes that the current Macintosh SONY driver 
returns. 


- $01 Initialize 


« $02 -— ShutDown 


¢ $03 -— StartPolling 

¢ $04 — StopPolling 

¢ $05 — SetHFSTagAddr 

- $06 — DriveStatus 
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* $07 - Eject 


¢ $08 — Format 


* $09 — FormatVerify 
* $0A — Write 

¢ $0B — Read 

¢ $0C — ReadVerify 


* $0D — CacheControl 


* $0E — TagBufferControl 

¢ $0F —- Getlcon 

Initialize 

Offset Length Dire 

$00 1 Itialize kequest byte ($01 

$01 1 

$02 2 

$04 28 

This needs to be the first call madete-+the+OP SWIM driver, 2 ally made by the SONY driver 


when it is first opened at system startup time. It causes the IOP SWIM driver to initialize its hardware 
and data structures, and return a list of drives that are connected to the system, what kind of drive they 
are, and an indication of the drive number to use to refer to them in future calls. 


The driver can theoretically support 28 drives, numbered 0 through 27. The corresponding byte in the 
List of Drive Kinds returned by the IOP indicates the drive kind for each of the 28 possible drives. 


The encoding of the Drive Kind byte is the same encoding used by the SONY driver control call 23, as 
follows. 


0 No such drive 

1 Unspecified drive 

2 400K only drive 

3 400K/800K drive 

4 400K/800K/720K/1440K drive (FDHD) 

5 Reserved 

6 Reserved 

7 Hard Disk 20 
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ShutDown 
Offset Length Direction Description 


$00 1 In ShutDown request byte ($02) 
$01 1 In/Out unused 

$02 2 Out Error Code 

$04 28 In/Out unused 


This call used to shutdown the IOP based SWIM driver. It is not currently implemented, or needed, 
and may be removed in the future. 


StartPolling 

Offset Length Direction Description 

$00 1 In StartPolling request byte ($03) 

$o1 1 é 

$02 2 

$04 28 

This call used to enable Hf IOP base(S i ing A ék insertion / eject requests. The 
Macintosh OS SO ake nolli A starts polling at driver open time. 
StopPolling 

Offset Length 

$00 1 In StopPolling request byte ($04) 

$01 1 In/Out unused 

$02 2 Out Error Code 

$04 28 In/Out unused 


This call used to disable the IOP based SWIM driver polling for disk insertion / eject requests. It is not 
currently implemented, or needed, and may be removed in the future. 


SetHFSTagAddr 
Offset Length Direction Description 


$00 1 In SetHFSTagAddr request byte ($05) 

$01 1 In/Out unused | 

$02 2 Out Error Code 

$04 4 In HFS Tag buffer address 
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$08 24 In/Out unused 


This call used to support the extended 20 byte HFS file system tags that are used on the HD-20. The 
first 12 bytes are also used by the 400K/800K floppy formats, and are passed in the message buffer, 
but there was not enough room for the 8 bytes of extended info, so instead the IOP is notified of the 
address of those 8 bytes, and when the IOP needs to access them it will send a move request to the 
main CPU requesting them. If this call is never made, or if a buffer address of zero is passed to it, 
then the IOP will not make requests for HFS tag data. 


Driv u 

$00 1 In DriveStatus request byte ($06) 
$01 1 In Drive number 

$02 2 Out Error Code 

$04 2 Out Track 

$06 1 Out 

$07 1 Out 

$08 1 Out 

$09 1 Out 

SOA 1 Out 

$0B 1 Out 

$0C 2 Out 

$OE 4 Out 

$12 1 Out 

$13 1 Out 

$14 1 Out 

$1 5 1 Out P O 

$16 2 Out Current Format (bit mask) 
$18 2 Out Formats Allowed (bit mask) 
$1A 4 ~ Out Disk Size (blocks) 

$1E 1 Out IconFlags 

$1F 1 Out unused 


Returns Drive Status information for the disk and the drive specified. The meanings of most of these 
bytes are the same as those used by many of the control and status calls to the SONY driver. Bytes 
$02 through $OD are used for status call 8. Bytes $0E through $11 are used for control call 23. Bytes 
$12 through $15 are used for status call 10. Bytes $16 through $18 are two 16 bit masks which are 
used to indicate the current format and formats allowed, for status call 6. The bits have the following 
meanings. 


BitO HD-20 disk format 
Bit1 400K GCR format 
Bit2 800K GCR format 
Bit3) 720K MFM format 
Bit4 1440K MFM format 
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The Disk Size in Bytes $1A through $1D also used for status call 6. Byte $1E is used for control calls 
21 and 22, to determine if the IOP based driver needs to supply the icons, or if the default icons used 
by the SONY driver is correct. This is used for the HD-20 drive which supplies its own icons. The 
bits have the following meanings. 


BitO 0-use default Media icon, 1 - call IOP for Media icon 
Bit1 0- use default Drive icon, 1 - call IOP for Drive icon 


Eject 
Offset Length Direction Description 
$00 1 In Eject request byte ($07) 
$01 1 In Drive number 
$02 2 Out Error Code 
$04 28 Out Same as DriveStatus request 


Ejects the disk from the drive species and returns Upaaies ane status reflecting the state of the drive 


after the disk has beg anings of the returned status 
bytes. 

Format 

Offset Length 

$00 1 

$01 1 

$02 2 

$04 2 

$04 28 Out Same as DriveStatus request 


Formats the disk in the drive specified, using the specified format kind, which the bit number of the 
format kind to use, as described in the DriveStatus request. After the format is complete, it returns 
updated drive status reflecting the state of the drive after the disk has been formatted. See the 
DriveStatus message for the meanings of the returned status bytes. 


FormatVerify 
Offset Length Direction Description 


$00 1 In FormatVerify request byte ($09) 
$01 1 In Drive number 

$02 2 Out Error Code 

$04 28 In / Out unused 


Verifies that the disk in the drive specified is correctly formatted, and that each block of the disk can be 
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successfully read. — 


Write 

Offset Length Direction Description 

$00 1 In Write request byte ($0A) 
$01 1 In | Drive number 

$02 2 Out Error Code 

$04 4 In Main CPU RAM address 
$08 4 In Disk Block Number 
$0C 4 In Block Count 

$10 12 In/Out Tag Data 

$iC 4 In/Out unused 


Writes Block Count disk blocks, using data starting at Main CPU RAM address, to the disk in the 
drive specified by Drive number, starting at ee Block peat using T ag Data for the first block 
written, and updating it for ea lock. Whe opmplete, error status is 
returned in Error Code, and Tdg Data is apdared to feflect the rage of fhe tet block transferred. 


Read 

Offset Length Direction 

$00 1 In st byte {$0B) 
$01 1 In 

$02 2 Out 

$04 4 In PU RAM address 
$08 4 In Disk Block Number 

$0C 4 In Block Count 

$10 12 Out Tag Data 

$1C 4 In / Out unused 


Reads Block Count disk blocks, into the data area starting at Main CPU RAM address, from the disk 
in the drive specified by Drive number, starting at Disk Block Number. When the read is complete, 


error status is returned in Error Code, and Tag Data is updated to reflect the tags read from the last 
block transferred. 


ReadVerify 

$00 1 In ReadVerify request byte ($0C) 

$01 1 In Drive number 
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$02 2 Out Error Code 

$04 4 In Main CPU RAM address 
$08 4 In Disk Block Number 
$0C 4 In Block Count 

$10 12 Out Tag Data 

$1iC 4 In / Out unused 


Reads Block Count disk blocks from the disk in the drive specified by Drive number, starting at Disk 
Block Number and compares the data from disk to the data in the data area starting at Main CPU TAM 
address. When the read is complete, error status is returned in Error Code, and Tag Data is updated to 
reflect the tags read from the last block transferred. 


CacheControl 

$00 1 In CacheContral request byte ($0D) 
$01 1 

$02 2 

$04 1 

$05 


of bytes are the same as the csParam 


$00 1 In TagBufferControl request byte (S$0E) 
$01 1 In Drive number 

$02 2 Out Error Code 

$04 4 In Main CPU RAM address 

$08 24 In / Out unused 


Specifies the Main CPU RAM adaress of an alternate tag buffer. And address of zero is used to disable 
the alternate tag buffer. The meaning of parameter is the same as the csParam bytes that are passed to 
control call 8 in the SONY driver. 


Geticon 


Offset Length Direction Description 
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$00 1 In Getlcon request byte (SOF) 
$01 1 In Drive number 

$02 2 Out Error Code 

$04 4 In Main CPU RAM address 

$08 2 In Icon Kind (O=Media, 1=Drive) 
$0OA 2 In / Out unused 

$0C 2 In Max Byte Count 

SOE 18 In / Out unused 


Specifies the Main CPU RAM address of a buffer to receive the icon data, the con Kind and the Max 
Byte Count of the receiving buffer. This call should only be used when the Drive Status indicated that 
the IOP should be called for icon data. 


IOP _ SWIM Driver Main CPU Regu Kin 


By convention, the first byte of any message associated with the IOP based SWIM driver will be a 
request kind. The request kinds for the IOP SWIM driver to main CPU messages are as follows. 


¢ $01 — Disklnserted 
* $02 — DiskEjectButfon 


¢ $03 - DiskStatusChanged 


$00 1 | tskincertGd request byt 
$01 1° Out Drive Number 

$02 2 Out Error Code 

$04 28 Out Drive status information 


Informs the main CPU that a disk has just been inserted in the drive specified by DriveNumber, and 
the new status for that drive is returned in Drive status information, which has the same format as the 
DriveStatus request. 


DiskEjectButton 

Offset Length Direction Description 

$00 1 Out DiskEjectButton request byte ($02) 

$01 1 Out Drive Number 

$02 2 Out Error Code 

$04 28 Out ‘Drive status information 
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Informs the main CPU that the eject button has been pressed on the drive specified by DriveNumber, 
requesting the system to eject that disk. The current status for that drive is returned in Drive status 
information, which has the same format as the DriveStatus request. 


DiskStatusChanged 


$00 1 Out DiskStatusChanged request byte ($03) 
$01 1 Out Drive Number 

$02 2 Out Error Code 

$04 28 Out Drive status information 


Informs the main CPU that the status of the drive specified by DriveNumber, may have changed, and 
the main CPU copy of the status may now be incorrect. The new status for that drive is returned in 
Drive status information, which has the same format as the DriveStatus request. 


oe 
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IOP ADB Driver ERS 


Gary Davidian 
ext. 4-4510 
MS 27-AJ 
Rev. 1.0 D1 1/18/89 


Introduction 


The Modern Victorian architecture, and Four Square and F19 implementations, contains two Input 
Output Processors (IOPs), formerly called Peripheral Interface Controllers (PICs) which are 
programmable input / output processors that have a shared memory interface with the main CPU 
(68030). By off loading some of the input / output tasks to the IOPs, the main CPU will have more 
free cycles and better performance in a multitasking environment. On the current IOP based CPU 
projects, one IOP will be connected to a SWIM disk interface chip. When the floppy disk is not in 
use, this IOP is fairly idle, and can be used to directly control the Apple Desktop Bus (ADB) which 
supports all input devices like mice and keyboards. This produces both a cost savings and a 
performance improvement by eliminating the need for, and cost of, the ADB transceiver processor 
used on the Macintosh II, and by oe the amount of ee and number of interrupts that the 

eS be Aa PU and the IOP is described 
at of the pee used to 


this document should not be 
is information should NOT 


the Macintosh II ADB Mfas essages to an IOP based ADB Driver, 
instead of accessing the ADB transceiver processor through VIA1. Although the code will be 
modified, the functionality of the ADB Manager will be unchanged. Additionally, the code for the 
mouse and keyboard drivers will not need to change, since they use the ADB Manager to communicate 
with their devices. 


In addition to processing the low level ADB transactions, and Auto Polling, the IOP based ADB driver 
also handles Service Request (SRQ) Polling without intervention from the 68030. SRQ polling 
usually occurs when alternating between multiple input devices (eg. switching between typing and 
moving the mouse), and requires polling all of the connected devices, searching for the device that 
needs service. The IOP code is written to optimize this process, by searching in Most Recently Used 
(MRU) order, so that devices that are rarely used will be searched last. This of course is not a real 
advantage unless you have three or more ADB devices (most systems have exactly two), but it will 
look great in some marketing spec sheet ("Advanced MRU based SRQ search algorithm."). 


There is one new feature that is needed to support the Columbo package. Columbo will have a key 
operated switch to lock the system in an unattended server mode. While in this mode, all ADB 
operations will be disabled, to prevent tampering with the system. . 
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mpatibili im 


Since the modified ADB Manager and IOP based ADB Driver will implement exactly the same 
functionality as the Macintosh II ADB Manager, any application or driver that runs on the Macintosh 
Ii, and accesses ADB devices through the ADB Manager, or through the Apple Mouse and Keyboard 
drivers, should not have any compatibility problems with the IOP based implementation. 


The ADB Manager has several low memory globals that point to internal routines and data structures, 
which are not documented in Inside Macintosh. Although their usage and structure is mostly 
unchanged, there are some changes, and any code the was directly accessing any of them may no 
longer work. This is also the case with the Harpo Power Manager based implementation of ADB. 


There is one area where I will make every attempt to avoid compatibility, and that is performance. As 
every Macintosh user is aware, when the Floppy Disk is active (especially when formatting a disk), the 
mouse isn't. This is due to the amount of uninterrupted processor time needed by the SONY driver. 
This situation can still occur on this IOP, since it is also servicing the floppy disks, but I am confident 
that with some fine tuning of the code, taking advantage of the DMA features of the IOP, and 
co-operation between these two IOP based drivers, a significant improvement over the "look and feel" 
of the Macintosh II can be achieved. 


by [the mager. Théformat and Zontexts of these messages is 
described below. Developefs should@-access the XDB devices by ust ¢ ADB Manager or higher 
level keyboard or mouse driversnd shuld NO'K communicate(irectlf with the IOP based ADB 


driver, just as they shouldntdirectly adcess the\ ADB transgFiver g ip on other system. The 
information below is to be yse@txternal to Apple for the Macinj Manager development, and 


An IOP based driver can recej wm the main C ill notify the main CPU when 
processing of the message reque empleted. It can alSOTettm information in the completed 
message. This method will be used for the main CPU to request ADB operations to be performed. 
The main CPU to IOP message number 3 will be used for this purpose. 


It is also possible for the IOP based driver to send messages to the main CPU, which will be used to 


notify the main CPU that an ADB device has some input data available. The IOP to main CPU 
message number 3 will be used for this purpose. 


1OP_ADB Driver Message Format 
Offset Length Direction Description 


$00 61 In/out Flags 

$01 1 In/Out Data Count 

$02 1 In/Out ADB command 

$03. 2...8 In/Out ADB data 

$0B 21 In/Out unused 
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The Data Count byte indicates the number of valid bytes in the ADB data field, which may be zero, or 
in the range 2 to 8 bytes. Its size does not include the ADB command or any of the other bytes in this 
message. The ADB command is either the command byte to be sent over the ADB bus, or the 
command that was sent that corresponds to the data that was received from an ADB device. The bits 
of the Flags byte are used as follows. 


Bit7 Explicit Command = 1, Implicit Command = 0 
Bit6 Auto/SRQ Polling Enabled = 1, Disabled = 0 
BitS unused 

Bit4 unused 

Bit3 unused 

Bit2 Service Request Detected = 1, no SRQ=0 
Bit1 Receive Timeout = 1, Received Valid data = 0 
BitO unused 


How the Messages are Used 


In order to process _ADBop traps, the ADB Manager can pass an Explicit ADB transaction request to 
the IOP ADB driver in two ways: The first, and most common way is for the ADB Manager to initiate 


an Main CPU to IOP_me : emessage to indicate that it is an 
Explicit Command, | and ais pass the’ A associated data (for an ADB 
listen command), setting the data count tg reflect the number of bytes of dd ta to be sent. When the IOP 
receives this message, ig quested transaction (but will not 
immediatly process jt), Ontil this transaction is actually 


processed, the ADB 


When the IOP actualyfini i it/will inftiate an IOP to Main CPU message 
request, passing back-the results of that trangaction (the Explicif Command bit will be set in the flags 
byte, and the Servige Req j fropriately). When the ADB manager 
receives this messa} , and if any new regjuests were queued, it can pass them to 
the IOP in the reply ‘ d way to make a request), otherwise, it 
must clear the Explicit Gemma Ley eply-and may want to enable Auto Polling. 


When the IOP ADB driver is Auto Polling, it will poll the most recently used device until it receives 
data, or until another device asserts Service Request. To handle a service request, it will start polling 
all of the other devices in most recently used order until it hits one that returns data. Once the IOP 
actually receives data from a device, it will notify the Main CPU, passing a message which will have 
the Explicit Command bit cleared, and the Auto Poll bit set. The Device address in the ADB Command 
byte of the message will indicate the device that sent the data; and the byte count will indicate how may 
bytes of the receive data buffer are valid. 


This method will reduce the interrupt traffic on the Main CPU when auto polling, to one interrupt each 
time a device has data, and requires no interrupts to direct the service request polling. This will 
hopefully reduce some system overhead. 
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EDisk Driver ERS 


Gary Davidian 
ext. 4-4510 
MS 27-AJ 
Rev. 1.0 D1 1/18/89 


Intr ion 


For the portable system environment, we have introduced several forms of Electronic Disks (EDisks) 

which appear to the user as very fast, silent, and low power disk drives. The data storage media for 

EDisks is RAM or ROM, unlike Hoppy or hard ee which record data on rotating magnetically 
dri 3] 


512K bytes, but they jare pected to expagd to 2 megabytes ag blogy progresses. There are two 


SLIM drives in the At two SLIM carg /be accessed concurrently without 
having to do disk sw 

The second form of EDisx is the AM Disk/which [ses a portion of the built in system 
memory for EDisk gtorage.{The usér may sglect the sizf M Disk in increments of 64K bytes, 
using the control partl. Un IM or floppy disks the inteynal RAM Disk is not ejectable (similar 
to hard disks), and attert ej Mill result in it being-renabunted (it will pop out of the trash can). 


Only a single internal RAM disk i is supported by the peter: ) 


The final kind of EDisk is the internal ROM Disk. These can be produced by third parties, and 
connected to the system using the internal ROM expansion slot. There is a four megabyte address 
space allocated for this type of expansion, and can support any number of ROM disks, as long as they 
start on a 64K byte boundary (but their size can exceed 64K bytes). They behave just like the internal 
RAM disk except that they are read only, and cannot be reseized. 


The EDisk Driver 


The EDisk driver provides a system interface to the EDisks that is similar to the interface provided by 

the Sony and SCSI Disk drivers. It supports 512 byte block I/O operations, and does not support file 
system tags. It will be a ROM DRVR resource, whose ID is 48, and RefNum is -49, with a driver 

name of ".EDisk". Since it is a disk driver, it will also create a Drive Queue Element for each EDisk 

drives. Information about how these driver calls apply to the Sony Driver already appears in Inside 

Macintosh, and in the Sony Disk Driver External Software Specification by Steve Christensen, and 

much of the information is duplicated (and copied) here. 
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Open 


The driver will allocate its global variables in the system heap, and setup a pointer to them in the 
DCtStorage field of the DCE (Device Control Entry). It will determine which EDisks currently exist, 
or could possibly exist in the future (SLIM cards being inserted later), and creates Drive Queue 
Elements for each of them. If no Drive Queue Elements are created (no EDisks can exist), then the 
-EDisk driver is not needed, and it will not allocate any storage, and will return openErr. The EDisk 
Driver is opened by the start code in the system ROM, so applications should never need to open it. 


Close 


The EDisk driver never closes, and will return closErr if a close is requested. 


Prime (Read, Write, ReadVerify) Call 


Read and write calls to Macintosh drivers are described in general in the Device Manager chapter of 
Inside Macintosh, Volume II, but for completeness they will be described here too. The device 
manager prime routines expect the following fie}ds-n the I/O parameter block to be set up : 


ioCompletion 
ioVRefNum 
ioRefNum 
ioBuffer 
ioReqCount 
ioPosMode 


ioPosOffset 


the ioTrap field of the parameter blO¢tkT6 either $A002 for a read Tequest or $A003 for a write 
request so the driver can determine what to do. Also, the dCtlPosition field of the driver's DCE 
will be set to the starting byte offset relative to the beginning of the EDisk. 


The EDisk driver can only be called synchronously or asynchronously. Immediate calls to the 
driver are not supported. Since the EDisks are accessed at memory speed, the driver is not 
interrupt driven, and the entire request is processed at the time it is issued. When the request is 
completed or aborted, it will return one of the following result codes: 


Result Codes: noErr 0 ‘i noerror 

wPrErr 44 write to a write protected SLIM or ROM EDisk 

paramErr -50 some of the requested blocks are past the end of the 
disk or ioReqCount is not a multiple of 512 bytes. 

- nsDrvErr -56 no such drive number supported by this driver 

offLinErr ~ -65 read/write request made to an ejected disk 

dataVerErr -68 read verify compare failed 

badDCksum -72 incorrect checksum while reading a block 
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ontrol Call 


Control calls perform all of the non read/write operations on a particular disk associated with this 
driver. The control opcode is passed to the driver in the csCode field of the I/O parameter block (byte 
26). Control calls that return information, pass it back starting at the csParam field of the I/O 
parameter block (byte 28). A description of each control operation is given below along with any 
result codes it returns. 


The Drive Queue is searched to file the DQE (Drive Queue Element) associated with the I/O request, 


returning nsDrvErr if not found. The following Control calls are supported, or cont rolErr is 
returned. 


Kill 1/0 (csCode=1) 


Kill I/O is called to abort any current I/O request in progress. The EDisk driver does not support 
this control call and always returns a result code of controlErr (-17). 


Resul S: controlErr -17._— Kill I/O not supported by EDisk driver 


Verify Disk (cgCode=5) 


ds _every-b 2 terify that all blocks have been 
written correct] ound to be bad, it ap6rts igimediately and returns one of the 


no error 
no such drivé number/supported by this driver 
request mage to an ej i 
1/O error While attenjpting to verify all blocks 
Format Disk (csCode=6) 


An index into a list of possible formats (or zero for backwards compatibility) is passed in the 
csParam field of the I/O parameter block to indicate how the EDisk should be formatted (see the 
Format List status call for details). The EDisk is then initialized, destroying all previous data, 
and writing valid checksums and data to each data block. A memory test is also run on the 
EDisk RAM to check for hardware failures. There is a special case supported for the internal 
RAM EDisk which allows an index of -1 in csParam, which in addition to formatting the EDisk, 
will remove the EDisk from the Drive Queue, preventing any further I/O operations to that EDisk 
(used when reseizing the internal RAM EDisk). 


Result Codes: noErr 0 si noerror 
wPrErr -44 format request to a write protected SLIM or ROM EDisk 
paramErr -50 format index in csParam is out of range 
nsDrvErr -56 no such drive number supported by this driver 
offLinErr -65 format request made to an ejected disk 
FmtlErr -82. RAM test of EDisk storage failed 
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Eject Disk (csCode=7) 


For SLIM drives (DiskInPlace field = $02,which means ejectable), if there is a card in the drive, 
it will be ejected, and when a card is reinserted in the drive, a diskInserted event will be posted 
so that the EDisk will be remounted by the operating system. Until then, any attempts to access 
that drive will return offLinErr. 


For the internal RAM EDisk (DiskInPlace field = $48, which means non-ejectable, but make 
eject calls anyway), the drive will be marked as offline, and when next polled by the driver (at 
least once a second), a diskInserted event will be posted to remount then disk. This provides the 
effect of the RAM EDisk "popping out" of the trash can in the Finder. 


Internal ROM EDisk (DiskInPlace field = $08, which means non-ejectable, and do not make eject 
calls), the drive will remain online, and when next polled by the driver (at least once a second), a 
diskInserted event will be posted to remount the disk. Eject calls are not expected for these 
EDisks, but if received, the EDisk will be remounted. 


Result Codes: noErr QO _—icnoerror 
nsDrvErr -56 no such drive number supported by this driver 


Return Physical Drive 


by a text string (which caff b 
"where" field of the "get infe 


hes 


Upper SLIM Drive 
Result Codes: noErr 3 no error 
controlErr -17.__— no icon available for this drive 
nsDrvErr -56 no such drive number supported by this driver 
Return Media Icon (csCode=22) 


This call returns a pointer to an icon describing the selected drive's media type, followed by a 
text string (which can be patched for international translations) that the Finder uses in the 
"where" field of the "get info" window. The supported media icons and strings are: 


: 
a 
202%! 
23 
Seeedte® 
sesasesses 
3 P 
H : 
: § 
3 3 
3 H 
: : 
: 


Upper SLIM Drive Lower SLIM Drive Internal RAM Disk Internal ROM Disk 


Result Codes: noErr Q _‘noerror 
controlErr - -17_ ‘no icon available for this drive 
nsDrvErr — -56 no such drive number supported by this driver 
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Return Drive Info (csCode=23) 


This control call returns a 32-bit value in csParam that describes the location and attributes of the 
selected drive. 


QW RO 


0=primary/1=secondary 
0=removable media/1 =fixed media 


O=internal/1 =externa 


The drive types supported by this driver are as follows: 


16 RAM Disk Drive 
17 ROM Disk Drive 
18 SLIM Disk Drive 


Status Calls 


The EDisk driver currently supports two status calls which are described below. As with control calls, 
the status opcode is passed to the driver in the csCode field of the I/O parameter block (byte 26). The 
returned status information will be passed back starting at the csParam field of the I/O parameter block 
(byte 28). 


The Drive Queue is searched to file the DQE (Drive Queue Element) associated with the I/O request, 


returning nsDrvErr if not found. The following Status calls are supported, or st atusErr is 
returned. 


Return Format List | (csCode=6) 


This call returns a list of all possible disk formats that may be done with the current combination 
of disk controller, drive and media. On entry, csParam contains a value specifying the maximum 
number of formats to return, and csParam+2 contains a pointer to a table which will contain the 
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list. On exit, csParam will contain the number of formats returned (no more than specified), and 
the table will contain the list of formats. If no disk is inserted in the drive, the call will return a 
offLinErr code.The format information is given in an 8-byte record as follows: 
7 0 7 07 0 7 0 
disk capacity in BLOCKS 


O=single-density, 1=double- ey 
reserved (0) 
1=current disk has this format 
1=number of tracks,sides,sectors is valid, 0=fields can be user-defined 


Since an EDisk is not a rotating magnetic storage device like other disk drives, it does not have 

tracks, sides, and sectors, So the TSS valid bit is set to 0, to indicate that those fields are 

considered to be a “don't care" as far as describing the format of the disk. The disk capacity, and 
“current disk has this format" fields are the only meaningful fields supported by the driver. 


Result Codes: noErr 0 no error 
paramErr -50 emis, Count in meer oram is<1 


Drive Status 


(0) current track 
( 2) bit 7 set=writf 
(3) disk-in-place? 


sae s) 
oa cube, disk is in the drive (ROM disks) 
$48=non-ejectable but call driver with ejects anyway (RAM disk) 
( 4) drive installed? 1=drive installed 
(5) number of sides: always = 0 (not supported) 
( 6) drive queue element: ( 6) qLink — pointer to next queue element 
(10) qT ype — 1=long drive size format 
(12) dqDrive — drive number 
(14) dqRefNum — EDisk driver's reference number 
(16) dqFSID — file system ID=0 
(18) drive size (low) low 2 bytes of 4 byte disk size (in blocks) 
(20) drive size (high) —_ high 2 bytes of 4 byte disk size (in blocks) 


Result Ss: noErr Q —_—noerror 
_nsDrvErr -56 no such drive number supported by this driver 
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implementation Details 


The remainder of this document describes some of the implementation details, data formats, and 
algorithms used by the driver that may be useful for third parties who want to produce ROM EDisks, 
and for the CDEV which is used to control the internal RAM EDisk. In general this information is not 
needed by other clients of the EDisk driver. 


Data Checksumming 


In order to provide better data integrity, the EDisk Drivers supports checksumming of each data block, 
which is computed when a write is performed to a block, and checked on every read operation. For 
each 512 byte block, a 32 bit checksum is computed by adding each longword in the block to a 
running longword checksum which is initially zero, and is rotated left by one bit before each longword 
is added in. The following assembly code example demonstrates the algorithm. 


lea TheBlock,a0 ; AO is pointer to block to checksum 

moveq.1 #0,d0 ; DO is checksum, initially zero 

moveq.1 #(512/4)-1,d1 ; loop counter for 1 block (4 bytes per iteration) 
@loop rol.l #1,d0 ; rotate the checksum 

add.l (a0) +,d0 Hi the data to the running checksum 


; ldop thrdugh each longword in the block 


4K, 2 mpans 128K, efc.). A tontrol panel CDEV is used to allow 
the user to specify Sr adjyst the size. At system starifp time/the startup code reads the size from 
parameter RAM, afd resefves the/space for the RAM disk at/the top of system memory (ending at 
MemTop), and sets\BufPtNa.pemnt peo it. This layge contiguous memory area is then broken into 


checksum. The second sectié Siitains the actual EDisk data blocks which are each 512 bytes in size, 
and this section is aligned to start on a 512 byte boundary. The EDisk driver locates a block and its 
checksum by indexing into the two tables, where the first entry in each table represents block zero. 


Internal ROM EDisk Details 


When the EDisk driver is opened, it searches the address range from the base of the system ROM to 
$00F00000 for internal ROM EDisks. An internal ROM EDisk must begin with an EDisk Header 
block, which must start on a 64K byte boundary (but may be any size). If a valid header block is 
found, it is compared to all other headers that had been found, and if it identical to one that was 
already found, it will be ignored, to eliminate duplicates that are caused by address wrap around. If it 
is unique, a drive queue entry will be created for it, and the driver will support it. Any number of 
we ROM EDisks can be supported by the driver, limited only by the address space allocated for 
ROM. 
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EDisk Header Format 


There is a 512 byte header block associated with ROM based, or ejectable EDisks. This is used to’ 
describe the layout of the EDisk, and to uniquely identify it. The general format of the header block is 
described below. The EDisk Header marks the beginning of an EDisk, and should occur at the 
beginning of the device that is used for the EDisk storage (eg starting at the first byte of a ROM SLIM 
card). 


EDiskHeader record 0,increment ; layout of the slim signature block 
HdrScratch ds.b 128 ; scratch space for r/w testing and vendor info 
HdrBlockSize ds.w 1 ; size of -header block (512 bytes for version 1) 
HdrVersion as.w 1 + header version number (this is version 1) 
HdrSignature ds.b 12 ; 45 44 69 73 6B 20 47 61 72 79 20 44 
HdrDeviceSize ds.l 1 ; size of device, in bytes 
HdrFormatTime ds.l 1 ; time when last formatted (pseudo unique ID) 
HdrFormatTicks ds.l A ; ticks when last formatted (pseudo unique ID) 
HdrCheckSumOff ds.l 1 ; offset to CheckSum table if present 
HdrDataStartoff ds.1 1 ; offset to first byte of data storage 
HdrDataEndOff ds.l 1 ; offset to last byte+l of data storage 
HdrMediaIconOff ds.l 1 ; offset to media Icon and Mask if present 
HdrDrivelIconoff ds.l 1 7 offset to drive Icon and Mask if present 
HdrWhereStroOff ds.l 1 eb beet fo GetIinfg : j Lf mresent 
HdrDrivelInfo ds.l 1 ; longwoyd for R present 
ds.b 5 block fis. reserved 
EDiskHeaderSize equ ia EDiskf heag@ér block 
endr 
HdrScratch is a 128 byte} sed for rdad/write testing gf RAM EDisks to determine if the 


memory is ROM or RAM. Q 


to identify this version of the ple the soy /like "Copyright 1988, Apple 
Computer, Inc. System Togfs 6.03 #8" migh# be used toAdentify a ROM EDisk. 
HdrBlockSizeisa2 rat indicayés the size ¢f the EPisk header block. The size is 
currently 512 bytes. 

HdrVersion isa 2 byte field that indicates the version of the EDisk header block. The version 


number is currently $0001. 


HdrSignature is a 12 byte field that indicates that this is a valid EDisk header block. The 
signature must be set to (hex) 45 44 69 73 6B 20 47 61 72 79 20 44. 


HdrDeviceSize isa 4 byte field that indicates the size of the device in bytes, which is probably 
greater than the actual usable storage space. For example a 512K byte ROM SLIM card would have a 
device size of 512K, even though some of those bytes are used for the header block, and checksums. 
One might also think of the device size as the offset (from the beginning of the header block) of the last 
byte of the storage device. 


HdrFormatTime isa 4 byte field that indicates the time of day when the EDisk was last formatted. 
The EDisk driver will update this for RAM based EDisks when the format control call is made. This 
information may be useful for uniquely identifying a RAM based EDisk. 


HdrFormatTicks isa 4 byte field that indicates the value of the system global Ticks when the 
EDisk was last formatted, which should be a fairly unique number. The EDisk driver will update this 
for RAM based EDisks when the format control call is made. This information may be useful for 
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uniquely identifying a RAM based EDisk. 


HdrCheckSumOff is a4 byte field that is the offset (from the beginning of the header block) of the 
checksum table, or zero if checksumming should not be performed on this EDisk. 


HdrDataStartoff isa 4 byte field that is the offset (from the beginning of the header block) of the 
first block of EDisk data. 


HdrDataEndofrf isa 4 byte field that is the offset (from the beginning of the header block) of the 
byte after the end of the last block of EDisk data. 


HdrMediaIconoff isa 4 byte field that is the offset (from the beginning of the header block) of the 
128 byte Icon and 128 byte Icon mask, which represents the disk media. An offset of zero indicates 
that the EDisk driver should use the default media icon for this EDisk. Ejectable EDisks must set this 
field to zero, since the icon is needed even when the EDisk is ejected. 


HdrDriveIconoff isa 4 byte field that is the offset (from the beginning of the header block) of the 
128 byte Icon and 128 byte Icon mask, which represents the disk drive physical location. An offset of 
zero indicates that the EDisk driver should use the default drive icon for this EDisk. Ejectable EDisks 
must set this field to zero, since the ico eeded even when the EDisk is ejected. 


HdrWhereStroOff jis a 4 byte ees thatjis the qffset aoe the Biers of the header block) of the 
Pascal string that des ip ce the ¢ ation for the EDA emmand. An offset of zero 


zero indicates that the ED isk driver ould’ uge the defaultfirive i fo for this EDisk. Ejectable EDisks 
must set this field to z€fOsssince the drive infojis needed een wh¢gn the EDisk is ejected. 


Open Issues 


At the time of this writing, SLIMs have been de-coupled from the Harpo CPU projects because the 
initial design of the SLIM connector design did not provide a software controllable eject or locking 
mechanism. This document describes what I think may be implemented when they are redesigned, 
and how the driver may behave at that time. If enough information about how the redesigned SLIM 
will work, and some sort of prototype hardware are not available by the time the ROM has to go Beta, 
it would be unlikely that the driver could support booting off of SLIM cards. 
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DebugUtil ERS 


Gary Davidian 
ext. 4-4510 
MS 27-AJ 
Rev. 1.0 D2 1/18/89 


Intr i 


Over the years, as new hardware designs were developed, we have been faced with the problem of 
needing changes to the debugger (MacsBug) every time there is a change in the hardware design of the 
keyboard or ADB interface. This can be avoided by removing the knowledge of how the hardware 
works from the debugger, and putting it into all of the new system ROMs. An trap interface can be 
provided for the debugger to use, so that it can be isolated from the changing world of hardware. 

While we are most concerned with MacsBug, this interface could possibly be documented for use by 
third party debuggers. 


1 Allows the debuggertO informs the system that it is entering the debugger, to allow it to 
do any cleanup that may be needed (like maybe switching out of idle mode on Harpo). 


2 Allows the debugger to informs the system that it is leaving the debugger, to allow it to do 
any cleanup that may be needed. 


3. Asks the system to run the keyboard interrupt handler if an interrupt is pending. Note that 
the actual keyboard data is NOT returned by this call, so the debugger should continue to 
use whatever means it used before (like patching _PostEvent) to get the actual 
keyboard data. 
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How to use it. 


A debugger must first determine if a machine supports this trap by comparing 
GetTrapAddress (_DebugUtil) with Get TrapAddress (_Unimplemented). It may 
want to do this both before and after patches are installed (to allow it to be retrofitted into older 
machines, or add functionality to newer ones). If it doesn't exist, then you're out of luck, and will 
have to use the older hardware dependent way. 


If it does exist, call it with function selector zero to see how much of it exists. If it doesn't meet 

your needs, you're out of luck (see above). If it meets your needs, use it as follows. When you 

are entering the debugger (eg. from a breakpoint, stepping, interrupt button), you should call 

en one to inform the system that it is in the debugger, before asking it to poll for keyboard 
ata. 


Once you are in the debugger, and expecting input from the user, you should continuously call 
function three to allow keyboard polling, and use whatever means necessary to get the actual 
keyboard data. 7 


When you are about to leave the debugger and return back to running application code, you should 
call function two to inform the system that you are done. 
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There is currently no ERS for the Device 
Manager revisions. 


There is currently no ERS for the serial 
driver revisions. 
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what we now recognize as an AppleShare file server (code named Holy Hand 
Grenade). 


The first product, Killer Rabbit, is file service built in to every Macintosh, thus 
enhancing the Mac networking experience. It is smaller, less performance 
oriented, simpler and has fewer features than ‘full-blown’ AppleShare. 
Killer Rabbit is MultiFinder friendly so it can run as just another application 
as well as running in the background with the Finder. The server software is 
small enough that it will be feasible to run it at all times on any Macintosh 
with at least 1 Meg of memory. To do this we are making a number of feature 
and performance to size trade-offs. Some of these include: 

e limiting the number of concurrent sessions to 5 

e reducing the number of exportable entities to 5 and 

e decreasing the number of open files on the server. 
Our current estimate is 175K for the personal version of AppleShare but we 
are working on shrinking this. Some other primary features that are part of 
Killer Rabbit are: — 

e everything that is Oi oui G6wn Macintosh is visible to“(and accessible 

by) you, no matter who created it; H : 

¢ it is easy to instalF aiid iniaintain (plug-and-play) 

° it must work with! 976 (thé dial-up actess product)“ 


The second product, Holy“Hand Grenade, ‘is the next vérsion’ of the 
centralized file server that we have today. It is intended to.replace 
AppleShare 2.0.1 in the field. It provides the capability for’ the file server to 
run in the background of a Macintosh and is MultiFinder/ friendly so that the 
machine can be used for,a multitude of-tasks besides file service (such as Print 
Server, Mail Server, 976 Sefver; Administration, ..:)" “All the features that 
currently exist in AppleShare will be available in this version in addition to 
others that are listed below. Holy Hand Grenade's features improve our 
current product significantly to provide a more flexible file server solution 
and a basis such that other servers can run on the same machine. 


The primary goal of AppleShare-1989 is to provide a platform of file service 
that leads a user from AppleShare infancy to adulthood; from a small 
network of three or four users sharing files on their own machines to a full 
sized network containing many servers that are central resources for a large 
number of people and services. File service from either server looks the 
same to clients. i.e. accessing a Killer Rabbit (personal) server looks the same 
to a client as accessing a Holy Hand Grenade server. 


1.2 Hardware Requirements 
Both Holy Hand Grenade and Killer Rabbit will run on a Macintosh Plus, 
Macintosh SE, Macintosh SE/030, Macintosh II, Macintosh IIx and Macintosh 


Page2 . Apple Confidential 


IIcx as well as all new Macintosh 68000-based CPUs with 1 Megabyte of 
memory or more. 


As in previous versions, AppleShare-1989 server volumes can be any of 
Apple's hard drives that are compatible with Macintosh, or a variety of third- 
party drives. A list of third-party drives that are "compatible" with 
AppleShare will be prepared by SQA. 


1.3 Implementation 


The Holy Grail is made up of several software pieces: the file server itself, the 
AppleShare Control program and the client/workstation. The workstation 
software is the same for both servers. It is made up of: 
e an External File System which traps file system calls destined for the 
server and converts them to AFP calls 
e a Chooser device package which is called by the Chooser when a user 
wants to logon to an AppleShare.file server. It puts up dialogs to guide 
the user through the logitr recs ‘and rors <apaeulty _ 
change/set user passwords. 
e an AFP translator idriver that sénds the AFP requests‘to Ke server as 
well as pecaving atfentioris” and, Server ‘méssages 


The actual server software’ itself (which Provides file sérvice/ harness is an 
application called AppleShare File Server. ‘(We will sélect two appropriate 
names for the two server products.) This application installs itself as a 
background task under single Finder or mins as an Application i in a 
MultiFinder partition. “Under MultiFinder, the menu bar! associated with the 
file server contains the staiidard-Apple, File and Edit tfiériu items as well as 
the ability to shutdown the file server. When a Macintosh is running only 
single Finder, the File Server is running as a background task, much as it does 
now, allowing one other application, such as the Finder, MacPaint, Print 
Server, etc. to be launched. To shutdown file service in the Finder case, the 
‘administrator’ must either shutdown his/her machine or launch the 
AppleShare Control program to do a server shutdown. 


The AppleShare Control Program for these two products will be somewhat 
similar. This program combines the functions of the current facade 
(displaying connected users, the activity indicator, the server volume list) 
with some features such as server messages and server preferences as well as 
any Administration functions that occur for that particular server. This 
application is separate from the actual file service. It can run with or without 
the actual file server running. It is launchable in the Finder as well as with 
MultiFinder. More details for each case of the control program are discussed 
in the following sections. 
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1.4 Compatibility 


AppleShare-1989 software is compatible with the existing AppleShare. PC 
and Apple Il compatibility are maintained in Holy Hand Grenade and Killer 
Rabbit, except that Apple II booting is not supported with the personal server, 
only with Holy Hand Grenade. AFP 1.1 and 2.0 are supported. In addition, as 
many of the major Macintosh applications as possible that run under the 
current Finder and MultiFinder will also run with the AppleShare file server 
on the same machine. 


1.5 System Software 


AppleShare-1989 software runs with System Software release 6.0.4 and System 
Software release 7.0. Neither Killer Rabbit or Holy Hand Grenade can run 
with a previous system because of changes to the Finder and MultiFinder that 
are necessary for the server to run. The new Time Manager that was put in 
6.0.3 is also required. We plan to include support for Virtual Memory in 
AppleShare-1989 so the servers can run in the//.0/ VM environment. 


~Ree 


Peeevevevveveceerree eee eee ree 


OOO aN 
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2.0 Common Features of Killer Rabbit & Holy Hand Grenade 


2.1 Server : Finder and MultiFinder Support 


Both servers in The Holy Grail run as background tasks on any of the above 
listed machines without limiting the type or number of other applications 
that can be launched (aside from the limitations imposed by the memory 
used). The servers run with both Finder and MultiFinder. Running as a 
background task in the Finder provides a low end, economical solution in the 
case where a server is on a Macintosh with 1 Meg of memory. Being 
MultiFinder friendly provides a more versatile solution for the current 
centralized server as well as the personal server. 


The reasons for providing MultiFinder support are twofold. First it will 
allow a number of other services to run concurrently with The Holy Grail 
servers in a standard environment. Second, everyone using a Macintosh is 
encouraged to use pierce! Si a a must be part of ihat trend. 


2.2 Server : Mount Points _ 

Killer Rabbit and Holy, Hand Giétiade.servers ‘eal enon a’ or rier of ahard | 
disk. The export points (or mount points) can be folders‘on the disk or the 
entire volume. A mount,.point includes all the objects’ contained within it. 
There will be one PDS.and one server folder per voltime on an AppleShare- 
1989 server. See next sections on details of how thjs i is done i in both servers. 


2.3 Server : Startup, ShutDowa and Intégrity 


The Holy Grail servers are convenient to startup and shut down. Startup is 
automatic if requested so that merely turning on the Macintosh results in the 
server being started automatically and the volumes and folders being 
exported. This startup happens quickly because the checking and repair of the 
Parallel Data Structure (PDS) is done on the fly rather than at server startup. 
This is very important in the Killer Rabbit case because a user does not want 
to wait long for his/her Macintosh to become available. Another important 
reason for doing this check and repair on the fly is that as we are no longer 
limiting the number and type of applications that can run on the same 
machine as the server, the chances of server outages increase with the. 
decreased predictability in the server environment. The PDS integrity must 
be preserved through this. 


This ‘on-the-fly’ checking can be done in part beacuse the structure of the PDS 
has been changed in The Holy Grail servers. There is no longer an entry in 
the PDS for every object in the server; only for those entries whose extra 
attributes have specifically set or requested (such as short name, ProDOS info, 
etc.). Thus, if there is an error in trying to locate a specific entry (this error is 
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usually ‘entry not found’) the entry is created at the time that it was 
discovered missing. 


Shutting down file service does not mean shutting down the machine with 
The Holy Grail. When the user quits the server application, the memory that 
the server has reserved for its use is released. Also, when Restart or 
Shutdown is selected from the Finder, the server (if running) does an orderly 
shutdown; closing sessions and resynching its data structures. 


2.4 Workstation : Deadlock 


The AppleShare code fixes a deadlock problem that occurs if multiple 
Macintoshes are running one of The Holy Grail servers as well as acting as a 
workstation. If Mac A issues a synchronous request to a Holy Grail server on 
Mac B at the same time that it is receiving a request for its server from Mac B, 
a deadlock can occur while the workstation is waiting for its outbound request 
to complete. The fix is a change to the-scheduling of File System I/O requests 
by the workstation. This ‘ix is dorie in the a code, not bw Mac File 
System code. : ‘ei aa 


H 
verrercereds 


2.5 Workstation: External: ‘Volume eo tiitésface 


We are creating a MountVélume tap that’ ‘can be used. a our onaae as well 
as others who need and-want to mount volumes without ising the Chooser. 
The mount trap brings up the standard Chooser Device Package mount 
window(s) if all the information. riecessary to mount a volume is not 
specified. This makes the user interfacé as consistent as possible. The 
programmatic interface to thesé éalls is : 


volStuffRec =RECORD 


zoneName : STR32 
serverName : STR32 
volName >: STR27 
volPswd : STR8 {if there is one} 
userName : STR32 
userPswd : STR8 { encrypted?} 
END 
_getVolMountInfo 
Inputs: volRefNum : INTEGER 


Outputs: —_ volStuffPtr : pointer to a volStuffRec 
errorcode :INTEGER | 
volNotMounted {if the volume asked for is 
not in the VCB queue} 
(*** fill in other error codes **) 
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{ This trap returns a pointer to the data structure needed to mount a volume. 
It is called when a volume is already mounted and you want to save the 
information needed to mount it again at a later time. } 


_VolumeMount 


Inputs: volStuffPtr : pointer toa volStuffRec 
Outputs: errorCode : INTEGER 
notEnoughInfo {if the zone and server 
names are not passed in} 
(*** fill in other error codes **) 


{ The mount trap mounts a volume using the information provided in the 
volStuff record. It brings up the standard Chooser Device Package mount 
window(s) if all the information necessary to mount a volume is not 
specified. Ata minimum, the zone | name and server name must be 
provided.} Se aah ae aes 


2.6 Workstation : Server peaee = 


The workstation now handles ‘the receipt a Gispiay of phtra shessages, 
described in the next section, that are serit from the server. “The maximum 
length of a server message is 255 characters. An example of how a shutdown 
message with a server: ee attached i isi : 


a "Monticello in Nets-R-Us" 


The file server is closing downin 10 minute(s) 
[11:08 AM on 3/22/89]. 


The server will be down until 10 o'clock tonight. 


Workstation ShutDown Dialog 
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2.7 Control Program : Server Messages 


The Holy Grail provides the capability to send messages from the server to 
logged on workstations/users. The different kinds of messages that can be 
sent are: 
© Shutdown : As well as sending when the server is going to 
shutdown, a message can be entered explaining, for example, why the 
server is going down, how long it will be down, etc. 
e Broadcast : allows a message to be entered that will be sent to all 
users that are currently logged onto this server. 
e User : allows a message to be entered that will be sent to a specified 
user or users. The user(s) is(are) selected via the Connections list of the 
Server Status Window in the Control Program. 
eLogin : allows a message to be entered that will be sent to any 
workstation when it logs onto this server. 


An example of how these server messages look from the server side is shown 
in the shutDown dialag-below..... | Doha 


Volumes: 


Cabernet 
LearningDise 


Number of minutes 
until shutdown? 


Accompanying Message: 


Connections: 


Pat Dirks 
<Guest> 
Ruth Hennigar 
Chris Zuleeg 
Greg Vaughan 


fs 
i 
v 


Mon, Aug 22, 19 
Activity: 


Server Shut Down Dialog 
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2.8 Control Program : Disconnecting Users 


There is a new command available via the control program that provides the 
capability of disconnecting a user session. This is accomplished by selecting a 
user or multiple users from the Connections list in the control program and 

choosing ‘Disconnect’ from the Connection menu item. This will look like : 


File Edit server MCR 
== Monticello SS 


Volumes: 


Cabernet 
LearningDisc 


Connections: fe Di : 
~~ Number of minutes .untiL... 


3 3 
<Guesb is! disconnected? 
3 
: : 
sd Saat ie 2G ee yi A AREEEE NEARED ORAL ANE RRREREE A! 
2 


Ruth Hennigar a — , 


reryaine pn mee x 
ficcompénying Message: 


Mon, Aug 22, 19]] <— = 
Activity: Cancel 


Disconnect User Dialog 


2.9 Control Program : Server Stats 


Some very rudimentary server statistic information is available in the two 
servers in The Holy Grail. The connect time and idle time of each logged in 
user is calculated and displayed in the connections window in the control 
program. These stats can be displayed or not by selecting Show/Hide Statistics 
from the Server pulldown menu. 


2.12 Server : Timeouts 


There are three places that the server has to change in relation to timeouts. 
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1) tRelease timer which is currently always 30 seconds, is being made variable 
in AppleTalk 2.0. It will be changed in The Holy Hand Grenade servers to be 
1 minute. | 

2) Retry timer should be set by the server using the echo protocol. 

3) 976 timer changes : ** kludge to handle 'non-echo' based calculation of 
retry time 


3.0 Killer Rabbit Features 


3.1 Server: Installation 


eve Mevere vecvevvevevereversessere™ 


time. The following dialog will come with the server name and owner 
name information in it so a user can view and and/or change it. 
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ee Server Setup 


Server Name: 


Dick Neiss File Server 


Server Owner: 


Password: 


Sie 
one) Ce 


| __ Server Settp Diglog 
If the owner of the server, wants’ to’change this: jo fovcuating a at a facie time, 


selecting the Setup item of the-Server mienu of the Contfol Program will 
bring up the following.dialog. ~ ‘ ‘ ; 


Next, a mechanism is’ ‘presénted ms whith the owner cant ee what 
portions of the disk(s) are to be exported: The maximum number of volumes 
and/or folders that can.be shared in Killer Rabbit i is 5. These are then 
prepared much the same way-as" vélumes are now “prepared. This is done via 
the following dialog. This can be changed via the Control Program with the 
**Share** item of the Server menu as well as from the Finder (see next 
section for details). 
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Folder: New Documents 


C_] Type: Folder 
Short Name 


am apps & utils : INewDocu.men 

© cd remote stuff Cl vowmePassword:[ | 
@ ClickArt 

2 Old U@G 

C7 New Documents 


Share with: 


@ Exclusive access to you 

© Full access to you & read only to all others 

© Full access to you & full access to all others 
(including guests) 

© Other 


© All my things 
© System 
© try this to see if it 


Coecns seecceces epeweeseonsooscoesoseesnoccooes: 


(00 0000000000000000000000000008 2005 O0TTREOEDETSOORET OES OST O8RLOS 908 COD CED ORE 940 OE COS EOS HOD OOS OOS CESSES O00 CORDED 


Contents: 3,557K, 92 files, 7 folders 
Created: Thu, Jan 5 3, 1989 at 3:41 PM 
| Modified: jhon, Feb 37. 1989 at 6: 10 PM 


SUSUS ETS TTS NSO NTT e TNT e ETT NEE 


siespie Sharing" ‘plalog 


The owner of the server-now can “Select how the mount point is to be shared. 
We have defined a few-defaults which are: 
Exclusive acces¢ to you - the owner of the server is the only one who 
can ‘see’ this mount point’ ‘Temotely i 
Full access to you-&read only.to‘all others - lobeinus 
Full access to you & full access to all others (including guest) - 
obvious.. 
Other - will bring up a new dialog (shown below) with the full set of 
access privilege options so a more sophisticated user can set appropriate 
access . 


Volume password (** should we change this to 'mount point password’ **) 
capability is provided with Killer Rabbit so if the owner of the server does not 
want to bother with users&groups he/she can set up specific mount point 
passwords which will limit the access to the particular exported entity. 
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Folder: New Documents 


-& Greg's SE (] Type: Folder 


. Short Name: !NewDocu.men 
© apps & utils 


© cd remote stuff [J Volume Password: Ld 


C ClickArt ena oe 
© Old U&G 

Ca New Documents 
C All my things 

© System 

© try this to see if it 


Owner Group Everyone 


Make Changes : 
Change All Enclosed Folders: 7 


Reever?’ Sane 
__ Owner: a ii a 


Group: 


3 
i : 
3 


| Advanced Sharing Dinios 


At this point, file service-ts available and’ the owner of the server or a Guest 
can log in remotely. ; 


3.2 Server/Finder : Exporting Folders ie 

As part of making Killer ‘Rabbit'an asy to use application, we are making the 
sharing of folders an easy task for a user to accomplish. In addition to the 
installation process and the control program, we allow the user to select a 
folder in the Finder and choose ***Export*** from a pull-down menu. The 
following dialog will be presented. 
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New Documents 


(| Type: Folder 


Short Name: !NewDocu.men 


C] Volume Password: [ 


Share with: 


@ Exclusive access to you 

© Full access to you & read only to all others 

© Full access to you & full access to all others 
Cincluding guests) 

© Other 


simple ae Folder Dialog — 


You will notice that this dialog looks remarkably similar to the one seen 
above. The options are all thé sairié; but the user“only gets to set’ them for this 
one particular mount point.--If the user selects-Other, he/; she sees the 
following dialog a i ae similar to the one pane): 


Ss New mt 
cx / Type: Folder / 
.. “Short Name: INewDocu.nien... 
Cc] Volume Password: 


See Folders: 


See Files: 
Make Changes: 


Change All Enclosed Folders: [_] 


Revert ‘Save 


Advanced **Share** Folder Dialog 
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Once a folder has been exported, it's icon on the desktop will change. Perhaps 
looking like: 


The opposite action is also possible from the Finder, i.e. when a user selects a 
folder that is already being shared, the **export** menu item is replaced with 
the **unexport** menu item. Choosing **unexport** revokes all other users 
access privileges to that entity. The server code has an interface that the 
Finder can call to set up a folder as exported or to ‘unexport' it. This can only 
be done when the server is running. NOTE : This feature obviously requires 
some Finder support. 


3.3 Control Program : Introduction 


Killer Rabbit's control :program -containg a number-of-features;some of which — 
have migrated from the current facade as well as the new features ‘such as 
server messages. The user- one Poe eit oa ‘part oF Scars ‘Rabbit is 
also part of this application... nee Ao ¢ 

We want to integrate the 976, Apple Maik and the Killef Rabbit services very 
tightly. This implies that there is one ‘admin’ for all of these services or at 
the very least one usefs ard groups file with a similar user interface. At best 
it means one application that can-be run, to ‘administer’ ail of these services at 
least as far as user arid group’ tanagentent is concerned.! More details on 
how this will actually be'implemented are still being: determined. 


3.3.1 Server /Control Program : Server Preferences 


Since the performance of applications running locally can be impacted by 
activity generated by the Killer Rabbit server running in the background of 
the same machine, it is important for the local user to be able to customize 
his/her machine. Customizing the response time (local versus remote) as 
well as setting auto-startup at boot is done via the Preferences option from the 
Server menu of the control program. These changes take place automatically. 
The following dialog is displayed. 
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Se Monticello 


Server Preferences: 


C] Open at startup time 


Response Time 


Slower Remote Faster Remote 
Faster Local Slower Local 


> 
s : 


z 


‘Server Prefefences a 

The response time can be ddjusted by dragging the vertioél bar‘in the display. 
3.3.2 Control Program 3 Fersonal Preferences ‘ | d 

An owner of a seeecal aves mdy wanyto tempdrarily fhange his/her 
identity while accessing the sérver machine locally. Killer Rabbit provides a 


mechanism via the Controt-programi to do this. The-following dialog is 
shown when the user selects Personal Preferences from the Server menu. 


S Pat Dirks File Server 


Personal Preferences 


You are: 


Chris Zuleeg 


Personal Preferences 


Page 16 Apple Confidential 


The possible choices for ‘you are’ are the list of valid user names which will 
be presented in a popup menu. When the owner of the server changes 
his/her identity in this fashion, he/she now assumes the access privileges of 
the new person until he/she changes back. 


3.3.3 Control Program : User & Group Management 


The user whose machine is running the server must have some way to 
manage users and groups so that others can logon to, and share files on, 
his/her machine. This is done via the Users&Groups menu item in the 
control program. When User List is selected from this menu, the following 
dialog appears. 


=== user List 


Any User... 
Administrator 


G 


Ruths-Peek Machine 


eaters, 


* 


‘. 
% 
“ 
: 


Z $ 
* iY 
3 
’ : 
£ ; 
ce > 
; : 
Ca ” 
. 
; 
" $ 
: : 
Delete : 
: : 
2 . 
é 
f ; 
xa . 
: 
; : 
z : 
F 
: é 
P) - 


: 
° 
2 


Meg a tee Us er List 
Double-clicking on the name of the user, or selecting the Get Info button, 


brings up the following dialog, so the person who is managing the users can 
set the login and change password options for this user. 
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== User: Ruth Hennigar 


BE Name : |Ruth Hennigar ; 
Password: [| Login Enabled [x] 


Change Password Enabled [Xx] 


Unda Saue_ 


[JJ Fun People 


[J2 ski bums 


RP AppleShare Team 


User: information ‘- 
When a user is to be alidel, ‘the’ ‘owner’ “of the Killer Rabbit server selects the ~- 
Add User item from the Usérs menu in the control program.” This brings up 
the preceding dialog with the namé and password fie}ils Saas 


Poss 
eS 


When Group List is delected from’ the Users&eGroups menu item, the 
following dialog appears. . 


== Group List 


[JQ Fun People 
(JJ ski bums 


PP. AppleShare Team 


Group List 


Double-clicking on the name of the group, or selecting the Open button, 
brings up the following dialog, so the person who is managing the user 
information can add or remove users to/from a group. 
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Adding a user to a group is done by. eieciie | the’ ‘add User, Watton. The list of 
valid users is presented and from this list a user (or users} ¢ can be selected to be 


=| === Group: Fun People 


7) Name : | Fun People 


[J Chris Zuleeg 
[J Greg Vaughan 
[J] Pat Dirks 

[J Ruth Hennigar 


Add Member Jetiete Member 


Members: 


See Vee eee Toe TCT TTC E NTE TE TEEN 


added to the group. Deleting is done by selecting the sale 
info window and choosing the Delete ae 


3.4 Server : Ejectable: media 


name in the group 


Floppies are iotable ‘with, Killer Rabbit. Both Cbs. and: iispies 

are ejectable while the server is running. A dialog is displayed if there is 
activity on the CD or floppy so someone does not eject it without knowing 
that he/she may be affecting someone else. (NOTE: This does not mean you 
can reinsert another CD and have it become an AppleShare volume 
automatically.) 
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4.0 Holy Hand Grenade Features 


4.1 Server/Control Program : Mount Points 


Folders and volumes are exported via a mechanism in the AppleShare 
Control Program. The total number of exportable entities (folders and/or 
volumes) on a Holy Hand Grenade server is 50. The dialog that will be 
brought up to choose what volumes and folders are to be exported and the 
privileges they will have is: 


Volume: Greg's SE 


Type: Volume 
Short Name: !Greg's.SE 
SeeFolders: {XI Oj. 
wu Make Ch ariges’: Bq ff Cl’ 
“S\ Change All Enclosed Folders: [_] 


{Save 


, 
000 000000 080 sex oveinoe c0e: 
ay 
‘, 
2 
- 


Revert | / 


Owner :| £3] Greg Vaughan 


Group : fF -g4- 


Contents: 3,557K, 92 files, 7 folders 
Created: Thu, Jan 5, 1989 at 3:41 PM 
Modified: Mon, Feb 27, 1989 at 6:10 PM 


. 


3 
$ 
3 
H 
: 
3 
3 
3 
3 
3 
a peace 
; 
; 
on reed 
H 
3 
0. re A 
H 
3 
3 
ai 
7 
$ 3 
$3 
3 ’ 
H 
3 


Mount Point Selection 


Choosing Open on a selected item will present the list of folders in that item 
(much like standard file) so that a user can select a folder as well as an entire 
volume to export. Once a folder or volume has been chosen for sharing, the 
owner of the server can set the appropriate privileges for that mount point. 


4.2 Server: Guest Access 
Holy Hand Grenade will come up with Guest access disabled. (Note: this is a 
change from the current AppleShare file server where access is currently 


enabled by default.) This means that it will require a proactive decision on 
the part of the ‘administrator’ of an AppleShare-1989 File Server to allow 
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guests to login, by insisting that they run the AppleShare Control program to 
do this. The reason for doing this is to prevent the situation where an 
administrator sets up a server and, without realizing it, allows anyone to log 
in with guest access. Basically we are trying to provide a more secure server. 
This default will only occur on new servers, not on those that are being 
upgraded. A dialog is displayed when upgrading an existing server that tells 
the user that Guest access is currently en/disabled and gives them a chance to 
change it at this time. 


4.3 Control Program : Introduction 


The AppleShare Control program in Holy Hand Grenade is a combination of 
the current facade functionality (shutdown, show message log, etc), current 
Administration and new features such as server messages which are | 
described in detail in the following sections. | 


4.3.1 Control Program : penvere Status. 2 


The current facade window is is now pereplaesd by a. a server status s winklow that 
comes up automatically when-the-Control Progranris‘taunched as’ “well as by 
selecting Show Status. ‘Window- from, the Server’menu. It behaves like all the 
other windows in that it is moveable and closeable. ae window that is 


displayed is : — *, 
Ss Montiets === 


Ad ol u imps: 


ee, Gabernet 
Learningbise™ 


Connections: 
Pat Dirks 

<Guest> 

Ruth Hennigar 
Chris Zuleeg 

Greg Yaughan 


Mon, Aug 22, 1988 9:55:40 AM 


Activity: 
iis eae (ae eee Oe 
idle busy 
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Status Window 


It can be closed by either clicking in the close box or choosing Hide Status 
Window in the Server menu. 


4.3.2 Server /Control Program : Server Preferences 


Holy Hand Grenade provides a mechanism for the server to be configured 
depending on how the machine running the server is to be used. The things 
that can be configured are: 


¢ number of user logins 

e response time of the local user vs the remote/server user 

e automatic startup (provided in case the machine is running with the 
Finder) 


Customizing the Holy Hand Grenade server will be done via the Preferences 
option of the Server menu-from-the-tontrol program.-The-following dialog is 
displayed. d j : 

eo Monticello * 
Server Preferences: 


? : 
‘ ’ : é 
* g . ‘ : : 
‘s, . no a 
- % wt a * : 
Naat e : 3 
ge p e n a $ a r " p | m B : : 
seal > “ 
ped fo rd : 
"eer, we - ‘ 
Se: om £ . 
en. gear” Jesroerennnannnecenane 


User Logins: 


Response Time 


Slower Remote Faster Remote 
Faster Local Slower Local 


Server Preferences 


The response time can be adjusted by dragging the vertical bar in the display. 
The number of user logins is any positive integer. Changes to the number of 
user logins will take effect when the server is restarted. This is indicated to 
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the user by a dialog. Any response time changes take effect immediately. 
(NOTE : The only difference in the two server preference dialogs is that in the 
Holy Hand Grenade case an administrator can change the number of 
concurrent logins.) 


4.3.3 Control Program/Server : Server Stats 


The connect time and idle time of each logged in user that is calculated and 
displayed in the connections window of the control program can be 
optionally saved to a file. There is a menu item (Save User Statistics) under 
the Server menu that allows the administrator to enable or disable saving of 
user statistics. He/she is prompted (via Standard File) for the name of the file 
where the information will be saved. When a user logs off the server, 
his/her name, connect time and idle time will be saved in this file. 
(WARNING : This file can get very big. It will be up to the Administrator to 
manage this, i.e. removing it when it gets too large and starting over with a 
new file.) 


: 
geveeevervevereecersscerewvererweneee sy 


: . 
coo CoCo oOo Cuin ont 
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4.3.4 Server/Control Program : Group Membership 


The number of groups a user can be a member of will increase to 42 in this 
version of AppleShare. 


4.3.5 Control Program : SuperUser 


Multiple SuperUsers are allowed, that is, users other than the Administrator 
can be granted SuperUser Privileges. Such a user, when logged in, has full 
access to all folders on all volumes regardless of the actual Access Privileges. 
This is done via the User Info window in Admin as shown below. 


User: Greg Vaughan 


Login Enabled [XJ 
mo" Ch Sge Passw of d En Sble d 4] . Ps 
3 ene NET All Priv ile 9g e s 4] ’ a : ‘ 


: | Gg Fun Peopi¢ 
EER ski bums 
“sul Cog-AppleShare Team 


User Info Dialog 
4.3.6 Control Program /Server : Application Launching 


Holy Hand Grenade allows administrators to limit the concurrent number of 
times an application is launched. An internally stored count is incremented 
whenever an application is launched and decremented whenever it is closed. 
The server checks this number before launching an application to ensure that 
the maximum has not been reached. The Control program interface is as 
simple as pulling down the File and Folder Info of any multi-launch 
application on the server and entering the number of launches allowed. 
Developers can add a resource to their application that specifies the 
maximum number of times it can be launched. When the Control Program 
brings up this dialog, it will look for this resource in the application and set 
the inital value in the menu to the maximum specified. We will not allow 
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- the maximum to be increased via this dialog. The following dialog shows 
how an administrator changes the user limit. 


= == File: MacPaint 


Locked [J 
Copy-Protected [_]} 


Name: 
Short Name: MacPaint 


Concurrent User Limit: [ 


save 


Size: 149,281 bytes 
Where: apps & utils on Cabernet 
Greated:..Thu,, Deé 17, VOSF at-44- OFM fecncreccnnnseinenrg 
daca Thu, May 5; 1988 at 2:07 PM : 


Fug and Folder Info” 


4.4 Print Server: Finder & MultiFinder Support 


The Print Server application runs as an applicationy Aer ‘MultiFinder and 
Finder. This means that a user. will be Said to as the Print Server 
application from the Finder. ~ ss bal 


4.5 Utility : Creating a User List 

A utility will be provided to create AppleShare users from an existing online 

list of names (say a classroom attendance list). The online file or list will 

have to be in a format of (for example) 7 

<name> <separator> <password> <separator> <group1> <separator>... <groupn> 
with the password and groups being optional. The password would default to 
the first eight character of the user name if it is not specified. The first group 
specified will be used as the primary group. 


Note : This item is only included here for completeness. It will be a separate 
effort from the actual Holy Hand Grenade product. 
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5.0 Outstanding Issues 


Are server messages (specifically with shutdown) worth the disk/memory 
space in Killer Rabbit? 


There should be a way to reserve a login for the owner of the machine so if 
he/she does not get locked out when trying to login remotely. Optional? 


Sharing Floppies.. are these worth the trouble? The general impression at the 
meeting was that they are not. Just how are we going to handle ejectable 
media anyway? 


Are we going to increase the maximum number of open files in HHG as we 
increase the number of simultaneous users? Do we have to have a 
maximum or can we yen) allocate the space we need? 


With Killer Rabbit, is there some way-a-key user can easily temporarily disable 
any other logins (except for himself)? Is it useful: to be able'to’ ey, 
‘unexport' a folder? | i ss 


Pea ARRAS RA REE ROE RARE, 
eS 


The roots of all sake 2 stacker ‘to"a. Killer # Ratbit server: énust ‘be accessable 
to the key user remot: Is.this automatic? erro j 


oo 
a 


Do we want the response. fime remotely t to ¥ 0 to absolutely 0?. logged in 
workstations will hang. : ; : : 


We need good phrases for Byport, , Untxport sai Mount Pooink 


New Finder is not currently scheduled for 6.0.x release. This implies that our 
Share command from the Finder will only be there in 7.0. 


We need to define the resource for limiting application launches. 


Should we decrease the maximum number of users and groups in Killer 
Rabbit? 


Guest being automatically disabled is a big issue. Can we get some customer 
feedback? 


Group level messages as well as user level. 


There is a new chooser for Big Bang. Can we make the changes to work with 
it to the Chooser Device Package? 


Should we use dragging in Killer Rabbit Admin stuff? 
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ABOUT THIS DOCUMENT 


This document provides an external reference specification for “976”. “976” is the code name for a project 
to provide remote AppleTalk access. The resulting software must integrate seamlessly into and enhance the 
existing AppleTalk Network System. Indeed, remote access is one of the components of the AppleTalk 
Network System. 


976 is a software intensive project. 976 is not dependent on any new hardware. A minimum set of 
functionality will be required for modems used. 


The ERS is organized as follows: 
Q 976 Project Overview 
OQ 976 System Requirements 
oO The 976 Remote Workstation 
O The 976 Server 


Oo Automated Connection Control 
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976 PROJECT OVERVIEW 


Remote AppleTalk access is a key component of the AppleTalk network system. A complete AppleTalk 
network system needs to provide access to both local and remote resources. Ideally, remote resources and 
services could be accessed in the same way local services and resources are accessed, with no burden on the 
user for setting up complex connections and configurations. 976 will provide this capability to the user by 
extending the AppleTalk network system's data highways without compromising the "plug and play" nature 
of the AppleTalk system. 


Currently, there are three or four third party products providing remote AppleTalk access, and others may be 
in development. Yet, this does not solve the problem for Apple. If Apple is to own and control its 
network architecture, it is strategically necessary that Apple provide a solution for remote AppleTalk access. 
976 will provide distinct advantages over current third party offerings. 976 will run on a Macintosh Plus, 
Macintosh SE, and a Macintosh II, with any AppleTalk lap, without the need for an external hardware box. 
976 uses an efficient remote procedure call interface on the remote link to minimize unneeded traffic on the 
link, resulting in data transfer rates faster then similarly configured third party products. 976 will integrate 
with the Apple Communication Server. 976 can be extended to provide multiple connection types (e.g. 
X.25, ISDN). 


976 will include the key building blocks for remote AppleTalk networking. The following functionality is 
included in 976: . 


° Asynchronous s¢rial remote link. 


Remote link profocol prrehre yompression 


Security: password 
976 server runs yrbe 


es e e e e 
tg 
8 
* 
tw 
fe) 
5 
9. 
72) 
i¢) 
bene 
=. 
o 
5 


AppleTalk Internet 


976 Server 
976 Configuration 


976 consists of two major pieces: the 976 workstation and the 976 server. The workstation and server are 


connected via the remote link. The 976 server is connected to an AppleTalk network, and when the 976 
workstation connects to the 976 server, the workstation is connected to the AppleTalk network. 
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976 SYSTEM REQUIREMENTS 


Both the 976 workstation and the 976 Server require a Macintosh Plus, Macintosh SE or a Macintosh II 
running System 6.0 or greater. Mac 512's and 128k Mac's will not be supported. All new Macintosh 
CPU's will be supported. Also, 976 will be shipped with current system software, so older versions will 
not be supported. 976 is designed to work with any AppleTalk LAP type. This includes LocalTalk, 
EtherTalk and TokenTalk which are produced by Apple. It is not clear at this time what subset of third 
party produced LAPs should be tested. With input from Marketing and Product Management, the list of 
third party LAPs supported (and therefore tested) can be compiled. 


Modems are required by the 976 Workstaiton and the 976 Server. The minimum requirements for the 
modem are TBD (to be determined). Transmission rates supported are from 1200 bps to 64 Kbps. The - 
internal modem of the portable Macintosh will be supported. 


The protocol used on the remote link by 976 is MNP (MicroCom Networking Protocol). MNP provides 
error control, data compression and adaptive packet sizing. In order to work with a wide range of modems, 
976 will provide MNP in software. 976 sends data to the modems asynchronously. MNP modems support 
synchronous communication across the remote link. 976 will support this optionally if both sides of the 
connection have MNP modems. 


Some modems have MNP built i in, For thgse 


modems, lds MNP can be ae off and the modem's built 


in MNP will be used. ry € 976]s process , s which have a MNP 
modem on one side, afd 976 software based on the other side will be supporte q. Some modems 
support only a subset pf the MNP Classes supported by 976, betber 976’can be configured to 
enable only certain P Glasses, relying on the modgm fr partial MNP 

976 is designed to be &@ remote extension of ppleTalk network. TXereforg, any network applications 
which work on Appleffalk sbetild Ws But there is one “atch. Bécause 976 will be transmitting 


data much slower and‘scroés a much m\re error pfone network thag alTalk, some network software 
_ may have difficulties. Problems arise due to longp r transmissioy delays. /It will be wise to verify that 
certain key network i 2 


On both the Remote Workstatrer-amdtiie Server, 976 will run in the system heap. The 976 Workstaion 
code requires about 20 Kbytes of memory. The memory is allocated when 976 is installed by the lap 
manager (either at boot time, or from the control panel). The Server requires aperonumerely 512 Kbytes of 
memory. 
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THE 976 WORKSTATION 


The 976 Workstation software will be packaged as an "ADEV" that the user places in the system folder. 
The "ADEV" is recognized by the Network control panel device (CDEV). 


Control Panel 
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The user invokes 976 by selecting the Network control panel device, and then selecting the "976" icon. At 
this point the user is presented with the 976 control dialog box shown below. 


976 


Remote AppleTalk Network 


Destination Network: Default Network 


Select Network... 
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The user can choose the destination network, connect if disconnected, or disconnect if connected. 
Additionally, the user can control the connection using the Chooser AppleTalk "Active" and "Inactive" 
buttons. If the user wants to change the destination network, the "Select Network...” button is pressed and 
the Black Book is invoked. For general information on the Black Book, see the Black Book ERS by Rick 
Holzgrafe. The Black Book presents the list of destination networks available. Destination network entries 
can be modified or deleted, and new entries can be added. An entry consists of two subrecords. There is a 
log on subrecord and a connection script subrecord. The log on subrecord contains the user name, password, 
destination phone number, and connection options. The user has the option to choose automatic 
connection on boot up, and the user name an password can optionally be saved to fully automate the 
connection sequence. The connection script subrecord contains a HyperTalk/Com script. This connection 
script allows 976 to work with many modem types and PBX types which require different commands and 
configuration. The HyperTalk/Com language is part of MacTerminal II and will also be used in 
MacWorkStation. The Black Book and the editors are shown below. 


Black Book 


Engineering Inte J Script Editor 
Headquarters 


InfoNet 


The Black Book, examining Chicago Sales Office Entry 
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§ 


Connect to 976 server "Chicago Sales Office" as: 


Name: Scott Leahy 
Password: [esos | (Scrambled) 
Network phone #: 9,3126855023 


Connect at system startup time &X. 


@ Save My Name Only 
© Save My Name and Password 


g the fmodem 


jsr 62 ! hangup 
inctries 
iftries 2 59 


dsplymsg “dialing the server" 
xmit ATSO=OEOMOS 12=20DT *USR3\ 13 


Script Editor 
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When the connection sequence starts, the user is updated on the progress of the connection by the 
connection progress dialog box shown below. Any error or problem encountered in the connection sequence 
is reported to the user. The connection sequence will involve call back for security purposes if the 976 
server is configured for call back. Call back can be enabled on a per user basis. Once the remote link is 
established, the remote machine is a node on the network and capable of accessing all network services. 


& Connecting to Chicago Sales Office Network... 


and: print the message. This leads to the next ‘problepy With the adv) emt of 976} it becomes clear that users 
will want to change LAPs on a freqrrent.ba PMs has to become e rordT. Currently, one might have 
to reboot his machine once or twice to change laps while not losing aay network services such as mail. 
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THE 976 SERVER 


~ The 976 server is a software package which runs on a Macintosh Plus, SE, or II. The function of the server 
is to connect remote workstations to the AppleTalk internet on which the server machine is a node. 


The 976 server runs as a background process which may be started as the result of the system INIT file, or 
by the 976 desk accessory. This server process lives independent of any applications that may be running. 
All of the server's actions are the result of interrupts such as AppleTalk calls completing or timers expiring, 
or direct calls from the 976 desk accessory. 


In 976, a simple single-user mode will allow individuals with modems at their desks to dial into their 
network. In this case, the workstation will double as a 976 server, and the node identity of the workstation 
machine will be shared with the remote workstation. A caveat is that the workstation on which the server 
is located may encounter some problems if it tries to access AppleTalk services. For instance, two 
processes are not allowed to open the same socket. Certain well-known sockets, such as the echo socket, 
would have to be owned by either the 976 server or by the server's local AppleTalk software, but not both. 
In later Phases of 976, the 976 server will also support several remote workstation connections on multiple 
serial ports. 


The 976 desk accessory will act as a front-end for the zs server, providing a user interface to the server, and 
2 , i accessory will add a menu to 


Orr ee re rrr errr rrrrirrrrrrriir rity 


Edit User List... 
Setup Ports... 36P 
Edit Scripts... 

Show Log 


Pree re ere rrr irri 


Install Server... 
Shut Down Server... 
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The 976 desk accessory will provide a server logging facility. By selecting "Show Log” from the 976 
menu, a pop-up menu allows the user to chose which ports to monitor. A window is created for each serial 
port to display a status line and log of all server activity associated with that port. There will be only one 
active port per server. Attempts to connect to the server — whether successful or unsuccessful, duration of 
connections, and any errors that occurred will be recorded. 


976 Log: Built-In Modem Port 


Status: Calling Timba @ 9,255-3386: 


|Fri, May 20, 1988 9:00:23 AM -- Hayes® V-Series Smartmodem 9600 
Fri, May 20, 1988 9:00:45 AN -—- remote login enabled 
Fri, May 20, 1988 9:02:12 AN ~-- connection established with Timba 
Fri, May 20, 1988 9:52:33 AM -- disconnected 
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The 976 server will maintain a database of users, their passwords, and privileges. To add, modify, or delete 
users from the user database, the administrator selects "Edit User List" from the 976 menu. A list of users 
will be presented in a window. For each user, the administrator provides a user name, password, an 
optional call-back number, and a list of zones the user has access to. 


=( = User List 


@ Timba-Zone 
@ Twilight-Zone 
® Bo-Zone 


zone List 
Poe se en a Re ee ed 


® We-B-Nets a 
® Timba-Zone ee Ey XxX] a 


© Twilight-con hX] Change Passwoyd Enab 
@e Bo-Zone 
e U-R-Here << 
© Cal-Zone 
@ Touch~Zone ( ) 
. y, 
@ Zone Buddis A 
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Automated Connection Control 


Due to the requirements of different modems and PBX’s, a connection control language is required to 
facilitate automated configuration, dialing, connect sequences, and username / password negotiation for the 
user. The language is also used by the server to control modems, validate usernames and passwords, and 
accept connections. The connection control language can be used in the implementation of security features 
such as a DES encrypt password and call-back. In fact, call-back can be implemented entirely in software 
without the need for expensive hardware. The connection control language to be used in the 976 product is 
HyperTalk/Com. This is a subset of the HyperTalk language and is being used by MacTerminal II and 
MacWorkStation. The scripts are created and modified by using the Script Editor in the Black Book. For 
completed documentation on HyperTalk/Com, see the MacTerminal II ERS. 


THE 976 PROTOCOL 


The 976 protocol is one of remote procedure calls made by the remote workstation to the 976 server. The 
server performs the various AppleTalk requests on behalf of the remote workstation. The server can be 
thought of as a surrogate. 


The protocol consists of messgges passed between the femote workstation and the server. These messages 

are of two types: commands ahd events. comments are messages sent from the remote wor}station to the 

server; events are messages passed fro othe remoje wg ; ay range from 
att: ef ¢ of opening the 


reference number. Additiona¥7 es es — those hassed from sg fver to rgmote workstation — 


pertains to. The class number for gram Delivery Proteee 


§ ) is one (2), whereas the 
class number for the AppleTalk Tansaction Protocol (ATP) is 6. 


Below are a list of the currently defined classes: 


976 976 Maintenance Protocol (undefined) 1 
DDP Datagram Delivery Protocol 2 
RTMP Routing Table Maintenance Protocol 3 
EP Echo Protocol 4 
NBP Name Binding Protocol 5 
ATP AppleTalk Transaction Protocol 6 
ADSP AppleTalk Data Stream Protocol 7 


The message id is used to specify a particular command or event within a class. Message ids ranging from 
1 to 127 are for command messages sent from remote workstation to server, while message ids 255 down to 
128 are for message events sent from server to remote workstation. The reference below lists each defined 
message by class. 
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976 976 Maintenance Protocol 
UNDEFINED - RESERVED FOR FUTURE USE 
DDP Datagram Delivery Protocol 
mman 
Open Socket 
class byte 2 
id byte =1 
refnum long 
socket number byte 
Close Socket 
class byte =2 
id byte =2 
refnum long 
socket number ne 
Write Datagrg 
clash 
id 
refn 
socket nu 
checRse 
des inate 
dd packet 
ddp packet 
Events 
Open Socket Result 
class byte = 
id byte =255 
refnum long 
result word 
socket number byte 
Close Socket Result 
class byte = 
id byte =254 
refnum long 
result word 
socket number byte 
Write Datagram Result OPTIONAL 
class byte = 
id byte =253 
refnum long 
result word 
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Read Datagram 
class byte = 
id byte =252 
refnum long 
result word 
received ddp packet variable 
RTMP Routing Table Maintenance Protocol 3 
mman 
Get Net Info 
class byte =3 
id byte =1 
refnum long 
Events 
Get Net Info Result 
class 
id 
refnum 
result 
network numbe 
node number 
bridge numb 
EP Echo P 4 
mman 
Echo Packet 
class byte 4 
id byte =1 
refnum long 
destination address long 
echo data variable 
Events 
Receive Echo Packet 
Class byte =4 
id byte =255 
refnum long 
result short 
echo data variable 
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NBP 


mm 


Events 
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Name Binding Protocol 
n 
Register Name 
class byte 5 
id byte =1 
refnum long 
interval byte 
count byte 
verify flag byte 
socket number byte 
entity name variable 
Remove Name 
class byte =S5 
id byte =2 
refnum long 
entity name variable 


interval 

count 

confirm address 
entity name 


Kill Outstanding NBP Command 


class 

id 

refnum 

kill call refnum 


Register Name Result 


class 
id 
refnum 
result 


long 


byte =5 
byte =5 
long 
long 


byte = 
byte =255 
long 

word 
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Remove Name Result 


class 
id 
refnum 
result 


Lookup Name Result 


class 

id 

refnum 

result 

number returned 
entity names 


Confirm Name Result 


class 
id 
refnum 
result 
socket numbe 


Kill Outstanding NBP Command Re 


class 
id 
refnum 
result 


ATP Apple 


mman 
Open ATP Socket 


class 

id 

refnum 

socket number 
request filter address 


Close ATP Socket 
class 
id 


refnum 
socket number 


02/04/88 


byte =254 


Protoc 


byte 
byte 
long 
byte 
long 


ou 
mt ON 


byte =6 


long 
byte 


Apple Confidential 


External Reference Specification 


16 


Project 976 


Send Request 


class 

id 

refnum 

socket number 

atp flags 

faux request tid 
destination address 
user bytes 
timeout 

retries 

number of bds buffers 
filler - reserved 
request length 
request data 


Send Request Through Socket 


Get Request 


class 

id 

refnum 

socket number 
request buffer size 


Send Response 


class 

id 

refnum 

socket number 

atp flags 

destination address 
number of response pkts 
number of bds buffers 
transaction id 

internal control flags 
response number 

user bytes 

response length 
response data 
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Events 
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Add Response 
class byte =6 
id byte =7 
refnum long 
socket number byte 
atp flags byte 
destination address long 
transaction id short 
response number byte 
filler - reserved byte 
user bytes long 
response length short 
response data variable 
Release TCB 
class 
id 
refnum 
request desti 
request trans4c 
Release Response CB 
class 
id 
refnum 
socket number 
filler - rese. 
request so 
request 
Kill Get Request 
Class byte =6 
id byte = 10 
refnum long 
kill call refnum long 
Kill Send Request 
class byte =6 
id byte =11 
refnum long 
kill call refnum long 
Open ATP Socket Result 
Class byte = 
id byte = 255 
refnum long 
result word 
socket number byte 
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Close ATP Socket Result 


class 
id 
refnum 
result 


~ Send Request Result 
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class 

id 

refnum 

result (element number) 
bit map 

atp flags 

faux request tid 
number of responses 
filler - reserved 

user bytes 

response element data 


Send Request Through Socket Reger 


Get Request Result 


Class 

id 

refnum 

result 

bit map 

atp flags 
requestor address 
user bytes 
transaction id 
request length 
request data 


Send Response Result 


Class 

id 

refnum 

result 

transaction id 

release packet user bytes 
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byte = 254 


byte = 253 


byte = 
byte = 251 
long 

word 

byte 

byte 

long 

long 

short 
short 
variable 


byte = 
byte = 250 
long 

word 

short 

long 
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Add Response Result 
class byte =6 
id byte = 249 
refnum long 
result word 

Release TCB Result 
class byte = 
id byte =248 
refnum long 
result . word 

Release Response CB Result 
class byte =6 
id byte =247 
refnum long 
result word 

Kill Get Request Res 
class 
id 
refnum 
result 


Kill Send Request Regult 


class 
id 
refnum 
result 


ADSP AppleTalk Data Stream Protocol fi 


EFINED - RESERVED FOR E USE 


THE REMOTE LINK 


976 supports asynchronous dial up connections for the remote link. Other link types can be added in later 
releases. Due to slow transmission rates and high error rates characteristic of asynchronous voice grade 
connections, the protocol used on the asynchronous link will support error control, data compression, and 
adaptive packet sizing. The current plan is to use MNP (MicroCom Networking Protocol). This code is 
not developed yet, and we are exploring the possibility of contracting with MicroCom to assist us in 
developing the MNP implementation. Details on MNP can be found in the MicroCom Networking 
Protocol Specification. 


DIAGNOSTICS AND TESTING SUPPORT 


Special calls to the 976 drivers will be provided to support diagnostics and testing. The exact calls 
supported are TBD. Calls wil! be provided to dump state, send packets (bypassing the protocol), and to 
introduce errors to check the protocols error control capabilities. 


02/04/88 Apple Confidential 20 


Project 976 External Reference Specification 


9/20/88 Apple Confidential 21 


2/18/88 


Evaluate 
Protocols for 


Async Link 


3/88 7/20/88 


976 Phase | Sabbatical 


976 Phase | 


ERS Draft 


9/8/88 


Link 
Protocol 
Choosen, 


ERS Draft 
1.0 
complete 


9/8/88 


Design and 
implement 
Connection 
Editor for 
BlackBook 


12/5/88 


FReemote 
Workstation 
ADEV 

pre-Alpha 


9/8/88 Release 


1/27/89 


976 
Phase | 
In house 

pre-Alpha 
release to 
9/8/88 


Complete RPC 
interface 


implement } 
Server 
Desk 

Accessory] 


9/8/88 


Complete 
Server 
Background 
Process | 


completed 


1/27/89 


3/3/89 


Debug, 
rework, 
Polish 


976 
PHASE | 


Alpha 
Release 


* Apple Confidential * 


Gene Tyacke 
Randy Carr 
Bob Otis 


Calvin & Hobbes Intro 


1.0 "Calvin and Hobbes" 


1.1 Introduction 


"Calvin and Hobbes" consists of two major services; software backup and 
restore (Calvin), and software distribution (Hobbes). Together they provide 
the user with a powerful combination of network tools. 


Calvin provides users with a fast and powerful backup and restore facility. 
The backup service provides both local (e.g. hard disk -> floppy) and remote 
network backups. For remote backups, Calvin utilizes an AppleShare server 
as a remote "spooler" to speed up backup operations. The administrator can 
optionally download information to a tape drive or other device for archival 
storage. Full AppleShare compatibility is provided including the saving and 
restoring of user and group infermation. Calvin is device independent for all 
q de u 


User's workstation software 
e Administration software 
° AppleShare server (described and furnished elsewhere) 


Both services rely on the concept of one administrator and multiple users. 
The AppleShare server is used as a receptacle for files and folders. By using 
AppleShare, there is no need to develop new products; instead we can 
leverage off of existing ones. If a user wants to use Calvin's local-only backup 
service, no administrator or AppleShare server is required. 


1.2 About This Document 
This document consists of three major sections: 


1.0 "Calvin and Hobbes" Overview — 
2.0 Calvin ERS 
3.0 Hobbes ERS 
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Since both Calvin and Hobbes are standalone applications, this document 
contains a separate mini ERS for Calvin as well as one for Hobbes. Each was 
written to stand by itself so some information is repeated in both sections. 
This document does not attempt to dwell on implementation or network 
protocol details. 


Both the names of files & folders and icons used throughout this document 
are fictionalized. 

1.3 System Requirements 

Calvin and Hobbes have the following system requirements: 


Workstation and em en pe 
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an, 
2.0 Software Backup and Restore (Calvin &) 


2.1 Overview 


The software backup and restore application provides a familiar, yet powerful 
utility to backup and restore volumes, files, and folders from both local and 
remote (networked) volumes. The entire software backup and restore system 
consists of a workstation agent, administrator agent and a specially setup 
AppleShare server volume to be designated as a Server Spooler. 


For local backup and restore services, only the workstation application is 
necessary making the use of the administrator agent and AppleShare volume 
optional. 


To provide the network portior ef the backup and restore service, the 
administrator dpplication provides rou > a Server Spooler 
ith some other adminj 


can be executed eifher remotely or dir¢ctlyon the re server. 
Any existing AjppleSp r Wolume can be ugéd ao/a Server Spooler, 
which really pray} Nace to store files afd folders for multiple 


users of the sy 


facilities to p 


a secyfe enviyonment. Pnly tie user and the 
administrator I e 


access to a 


2.2 Architecture 


The architecture of Calvin allows each agent in the backup and restore system 
to be a separate process, though nothing prevents one or more agents from 
residing in the same system and running simultaneously. 


2.2.1 Network Protocols 


Since Calvin uses AppleShare for transferring files, the Apple Filing Protocol 
(AFP) is used as the filing protocol for AppleShare. AFP provides a fully 
implemented and tested filing protocol. By using AFP, development of a new 
network filing protocol is unnecessary. 
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Workstation 
Agent 


AppleShare 


as 


Backup 


Communications AFP 
Protocol 


Server 


Remote 


Management 
Utility 


messages between thk 4 8 . This is shown 
in Figure 2-1 as the Be (BCP). These messages 
include simple text nxéSSages (chayacter stfings) that/indicafe status of a 


workstation, file request 3 iog, and remote backup 

‘ ill cause a 
workstation agent to bes : albo be possible to 
allow remote processes (e.g. 008) to use BCP to view status information and 
initiate backup sessions. 


Detailed information on AFP and BCP can be found in their respected 
documents. 
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2.2.2 Server Spooler 


The Server Spooler folder structure is as follows: 


<q 


Tennis 


HiFi 
Server Folder Calvin & Hobbes 


/ packup \ oe 
O ) O 
Admin Carr Ty acke User n... 
| SON 


fafa OO QO 


Admin Info HD HD2 Yol! Vol2 Volumen... 


yer Spooler Folder Structure 


All files backed 


special user's f Backup alvin & Hobbes 
folder of the server Tennis). backed up with the 
entire pathnamp of the rce volyme preserved./For few or changed files 
being copied toth¢ Server Spooler volume, a folder with the same name as 


the source volymesis created, and tHe files are flaced/inside that folder 
accordingly. Jn Figure 2-2 ybove, tmere are two volymes that have been 
backed up (either theentire ial volume), called HD and HD2 which are 
shown in gray. 


Once files have been spooled to the Server Spooler, the files are accessible by 
the administrator. The files can then be backed up to another destination 
such as Tape, or even another Server Spooler volume. It should be noted 
that the user always has full access to his files through the Finder; the 
AppleShare owner of the file's directory is the user. 


2.2.3 Administrator Application 


The administrator application contains a superset of the workstation 
application. It can backup local or remote (AppleShare) volumes, but it is the 
only one that can backup Server Spooler volumes. Every time the 
administrator performs a backup of files on the Server Spooler volume, a 
special file is created or updated in the user's folder in order to keep track of 
which files and folders were copied to a particular media. This file, known as 
an Evidence File, is present for each volume that a user has placed on the 
Server Spooler that the administrator has backed up. 
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2.2.4 Evidence File 


The Evidence file contains a directory of files/folders that have been backed 
up from the Server Spooler as well as the destination media information. 
The file allows the workstation application to determine which files have 
been actually removed by the administrator, but are still available on some 
other media, such as tape. It does this by a comparison of which files are 
actually present on the server versus which files the Evidence files contains. 


If the workstation wanted to restore files or folders present in the Evidence 
file, but removed from the Server Spooler, a message would automatically be 
generated to the administrator application asking for the files to be restored to 
the Server Spooler. If the requested information is immediately available, it 
is automatically copied to the Server Spooler and the user can continue with 
the restore. If the administrator is not online the user would have an option 
to cancel the operation. 


2.2.5 Space Requiremé¢ 


Since the Server Spoo 
each Server Spooler ca 


20MB hard drive, thé mos\efficiery#t methgd would ve Server Spooler 
space equal to the te s ldcal volutes or $0MB in this 
example. This would\provi of fast backfap opeyations (relative to 
Tape or Floppy backups). HtiOn, the adminiStre ould never be 


required to download and remove files off the Server Spooler making restore 
operations a snap. He could, of course, download files just as an additional 
safety measure. 


On the other hand, if the Server Spooler volume was very small (e.g. 20MB) 
and a user had a large volume to backup (e.g. 80MB), it may make more sense 
to use a local backup mechanism instead of Calvin's networked backup 
service. 


In the normal case, a middle ground must be reached; that is, there will 
probably be sufficient space for small incremental backup operations, but not 
enough space for saving every user's entire volume. 


To do this, Calvin incorporates an automatic smart download feature. This 
feature provides for the administrator application to automatically download 
and remove files off the Server Spooler when space requirements justify it. 
The administrator must still provide remote storage in order for this to work. 
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2.2.6 Background Operation 


Since backup and restore operations can take long periods of time, Calvin will 
be able to provide backup and restore operations in the background (under 
MultiFinder only). No user intervention is necessary to activate this; by 
switching to a new application in MultiFinder, current operations will 
automatically continue (albeit more slowly than if the user stayed in the 
Calvin application). If necessary, background operations can be easily turned 
off by pausing or cancelling the backup or restore from within Calvin. 


2.3 Features 

° Backup & Restore of Both Local and Remote Volumes 

e Automatic Timed Backups 

e Local or Remote Administration 

° Administrator Initiated Backups of Workstations 

° Automatic Smart Do xq (to relieve disk space problems) 
° No Special Server Required; Useg Existing Appleshare Server 
° Fully Ap ulti- ili 

° MultiFin 

° Hard Digk 5 

° Ability tq Olderformat Tapes (Ve ackup 1.0 & 2.0 files) 
e Media Indegendencé\on HF§ Mountable Noluy 

° Optional Compression and Encryption of Files 

2.4 Setup 


Since Calvin's Backup and Restore services can be either local or remote in 
nature, there are two possible configurations: Local only or local and remote 
services. For local only workstations, the setup is as simple as copying and 
then running the workstation application. 


Setup of the remote portion of the software backup and restore system 
requires three main steps: 


° Install the workstation software on workstations 
4 Setup the AppleShare server 
e Install the administrator software on the administrator's machine 


It should be noted beforehand that the actual setup of each of these pieces will 
be done by some type of installer mechanism. The descriptions of the setups 
below includes details the user may not need to know. 
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2.4.1 Setup of the AppleShare Server 


To provide remote (network) backup & restore functions to workstations, an 
AppleShare server volume must be chosen to act as a Server Spooler for 
Calvin. The Server Spooler will provide a storage area for each user of 
Calvin, as well as separate administrator functions. Enough storage space 
must be provided in order to serve all the needs of all users of the Server 
Spooler. For example, for three users each having 20 megabytes of local 
storage, at least 60 megabytes of storage space could be used by just these three 
users. 


For ease of administration, both the Calvin's administrator and the selected 
AppleShare server administrator should be the same individual. In fact, it is 
a requirement that the administrator of Calvin must be a superuser of the 
AppleShare server. The superuser is a necessary requirement for Calvin due 
to the fact that each user owns his own folder on Server Spooler. Owning the 
folders provides security from tampgrityg by other users, but in order for the 
administrator to backup each user of the Seryer Spooler, the administrator 
must have complete Access to that usey’s folder. 


or more groups for uSe¢ 
registered user on thg-sexyer and Yelong tp a specifi¢grouy. This group name 


administrator appliXation. 


An INIT file, called “Server Backup Prep”, must be copied into the server 
folder of the AppleShare server. This file provides a naming mechanism for 
the Calvin workstation and administrator applications to find those 
AppleShare server volumes setup as Server Spooler volumes. 


After restarting the AppleShare server, the AppleShare server will be named 
on the network as a Server Spooler volume. 


2.4.2 Workstation Installation 


The workstation installation is in two parts: the Calvin workstation 
application and its accompanying INIT file, called “Workstation Backup 
Prep”. 


The workstation application can reside anywhere in the system, including on 
another volume or even launched multi-user from an AppleShare volume. 
All workstation application preferences and other information is stored 
locally in the system folder of the startup volume. 
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The Calvin INIT file must be in the system folder of the user's startup 
volume. This file includes routines for executing automatic (timed) backups, 
as well as administrator initiated backups. 


2.4.3 Administration Installation 


The administration installation is similar to the Calvin workstation in that 
there is an administrator application and an accompanying INIT file. Since 
the administrator is a superset of the workstation, all the same rules apply 
when installing the administrator application and administrator INIT, called 
“Admin Backup Prep” which is contained in the system folder. 


The administrator also includes routines to setup the Server Spooler. This 
setup should be performed as soon as the AppleShare server volume has its 
“Calvin” group name added, the “Server Backup Prep” INIT file added, and 
the server restarted. 


2.5 Workstation 


for any voime/ffresent in the system. 
er restored inpMide AppleShare servers and 
any desktop mo , _ Mdditionally/ the workstation can backup 

am ? e servef previousfy setup to be a Server Spooler 
volume. Thig volume is jyst an AppleShard servey volume that has special 

é oY e backup/restore administrator 

application. TheSerue ér provides ick Femote backup mechanism 
for storage, plus the added benefit of having the ability for an administrator to 
download files stored on the Server Spooler to tape or some other media 
which normally would not be a good candidate for remote file transfer. All 
backup and restore operations are essentially media independent and require 
only that the volumes be ‘desktop mountable’. Calvin also provides the 
usual local volume backup to floppy diskettes; dividing files across diskettes 
if necessary. 


Volumes containing the files and folders that are to be backed up or restored 
need to be specified, and this is done from windows known as a backup and 
restore sets. 


First a new set window is created, and source and destination volumes are 
specified by dragging the desired volumes from the Volumes window on to a 
backup/restore set window. As a source volume is chosen, the file list of the 
set window becomes active and displays the volume and a hierarchical view 
of the files on that volume. 
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Initially, the list of files defaults to the entire volume, but a finer control to 
the backup/restore process is provided by using series of filters to create a 
selective list of the files intended for backup/restore. The list is built by 
specifying certain criteria from the filter menu. The filter criteria consists of: 


° File Types Application file types [MacWrite, MacPaint, etc.] 
° File Colors Finder colors 

° File Names Partial or exact match to any file name 

° File Dates Files later or earlier than Modification, Creation, 


Backup date 


Once a filter is created, it is saved in the backup/restore set. Additionally, files 
can be selected in the file list and manually removed (cut). A full undo 
facility is provided so that all files that were previously removed can be put 
back one at a time until the entire list of the volume is elles There is 


also an option to show.a with the 
ability to replace eachfentry by selectin 

Only files and foldersjactnall A up“or restored 
Note that the entire pp ed; jf. if any folder 
is removed, all the fil 

The main goal to the-workstation Application is to pfovidd'a simple visual 
interface when selecti and files p and then 
continue to use this . ifn. The code will be able to 
run in the backgrounc [bt d automatically to 


log on to the backup Server Spooler and execute a backup operation at some 
predetermined time, or a backup process can be started remotely from the 
administrator application. 


Once a backup or restore set is made, it can be saved on the startup volume 
for later use or immediately started. 


For Server Spooler volumes, each user owns a single folder on the 
AppleShare volume which is used to store the backed up files and folders 
(Figure 2-2). For each volume backed up, there is a single folder named the 
same as the volume's name representing the entire path of that volume. It is 
necessary to preserve entire pathnames in order to perform incremental 
volume backups. 


A backup or restore process is started by creating a new backup or restore set 
and selecting source and destination volumes for the operation. Backup and 
Restore sets are distinct from each other as the restore operation is based on 
files that have already been backed up to a particular volume. 
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2.5.1 Workstation Flow 


Initially, when the workstation application is started up, an untitled backup 
set window appears (Figure 2-3) which has been preset to backup from the 
startup volume (source) to some default destination volume (destination). 
Two other windows which the user may wish to open are the Status window, 
shown in Figure 2-7, and Volumes window in Figure 2-8. 


2.5.1.1 Backup Sets 


The backup set window (Figure 2-3) has three major sections: The upper area 
displays the source and destination volume specification ‘slots’ separated by 
the Start Backup button. The middle area indicates the backup method, 
source volume file/folder filter, an automatic backup time, and information 
about what is contained in file/folder list below. The bottom displays the 


file/folder list which specifies the actual files and folders of the source 


volume that should be backed zp 

eeu aaa 
———— a 
al 
\_\ 


Method: 
Time: 
List: 


$ 


4 


Figure 2-3 : Initial Backup Set 


As shown in Figure 2-3, the source volume is titled “HD” and the destination 
volume is “Drive 1” (a set of diskettes will be used in this case). The user can 
change either volume by either dragging a new volume icon from the 
Volumes window or by clicking on the icon area directly to cycle through 
currently mounted volumes and devices. The backup method is Incremental 
Append which means if the user is backing up to a previously backed up 
destination, new files will be appended instead of replaced (see menus for 
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further discussion). No filtering of files has been specified, i.e. “All Files” will 
be backed up. No automatic backup time has been specified. And the 
file/folder list contains, and therefore will backup, the entire volume “HD”. 


0 ESS Backup Set - “Untitled 1” 


aS >> Start Backup >>» 


HO 


Method: Incremental Append Filter: All Files 
Time: No Automatic Time Specified 
Figure 2-4 : Starting the Backup Process 


Clicking on the Start Backup button (Figure 2-4) will change the button name 
to Stop Backup (Figure 2-5) and immediately begin the backup process. The 
file/folder sizes will pe-eatewlated-a emedia-the-number of 

: s required, an alert will be 


~ 


Method: Incremental Append Filter: All Files 
Time: No Automatic Time Specified 
Figure 2-5 : Stopping the Backup 


Clicking the Stop Backup button suspends the backup process and a dialog 
(Figure 2-6) appears querying whether the backup process should be stopped 
or paused. 
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Are you sure you want to stop the 
current backup in progress? 


Figure 2-6 : Stop Backup Alert 


When the backup process begins, an entry will appear in the Status window 
(Figure 2-7). The user may have to open this window by using the Windows 
menu if it is not currently visible. 


eee telat ate! 


aluin User: “Carr” 


RUILILITILASARIL 


RAAARARRERREA 
pitstitesssssatssesssseesscaeay 


Operation: Backup HD to Drive 1 Backup Set: “Untitled” 
Status: Backup in Progress... Files remaining to be backed up: 123 


Progress: 


Neen et rrr rrrriRAISRRARARRRER RRA RR RARARRRRRRRRRRR ARRAS EEE ETE EEE EEE 
PRARRARRARARRERARARRARERERARR AAR RRR AREAL A RAR RR RARRR RAR RARER RAE A REA SEER oe So oU EE 


gtessassesse 
rsississ 
ESTIESON 


Figure 


The Status window contains information specific to the workstation’s status 
as it pertains to backup and restore. Currently active backup and restore set 
files are displayed in the list area and provide an at-a-glance view of the 
backup and restore operations. 
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The progress of any set in this window can be displayed by selecting the entry. 
The progress information is displayed in the bottom of the window. The 
percentage complete will be indicated by the bar graph. 


Double clicking any entry in the Status window will open the set listed by that 
entry or bring that set to the front if it is already open. 


The Volumes window (Figure 2-8) displays the all desktop mountable 
volumes currently online in the system as well as SCSI devices, such as Tape, 
and floppy drives with or without media inserted will appear as icons. This 
window can be opened using the Windows menu. 


Volumes 


_" 


Tennis 


afese 
srsges 
g3gsgs 
sa3ti 


Figure 2-8 : Volumes Window 


As each volume icon is selected, information pertaining to the volume will 


appear in the information area as shown above. The types of icons displayed 
include, but are not limited to: 


Figure 2-9 : Some Device Icons 


Icons that represent volumes or media not online are grayed in the icon list. 
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pes ke 


Since Server Spooler volumes are actually AppleShare volumes, both 
volumes will appear in the volume list. This means that the user can 
actually backup his accessible files in an AppleShare volume to the user's 
Backup folder on that same volume. When a Server Spooler is selected, it 
will show the same information as its corresponding AppleShare volume 
would, but the Kind field will display: Spooler. . 


Server Spooler volumes are added to the Volumes window by clicking the 
Add Spooler... button or by choosing its menu command. It can be removed 
by selecting the Server Spooler volume and clicking the Remove Spooler 
button. 


Adding a Server Spooler volume displays a dialog in Figure 2-10 similar in 
some respects to the chooser, but only displays AppleShare servers that have 
volumes setup as Server Spooler volumes. By using this mechanism instead 
of the Chooser, we are able to keep track of spooler connections and update 
status information directly to the administrator. There is, however, nothing 
preventing a user_from_earlierJogbing onto a verver Spooler volume using 
the Chooser. 


area of the Add ... dialdp, Server Spooler servers ound on the . 
network will ap i i \ The user sele¢ts a #rver, fills in the user 


ES A A AS LT 


a 
CG Twlight Zone 


xy 


Password: 
Cancel 


Figure 2-10 : Server Spooler Connection Dialog 


If the log on is successful, another dialog (Figure 2-11) appears displaying the 
Server Spooler volume list. 
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Volume Name: 
# Tennis © 


Passisor ii [ 


Cm) 


= edad notifying the usr that/he must log off 
to ensuye that fe is a registered 
user. 


As mentioned earlier, there ar@é two ways to specify different source and 
destination volumes in a backup set. The primary way is to click and drag a 
volume icon from the Volumes window onto one of the volume ‘slots’; 
source volumes are always on the left, destinations on the right. This is 
illustrated in Figure 2-12 below. 
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Backup Set - “Untitled 1” 


eSaey . Wx 


(2) 
=) Tennis 


Size: 292,,7Q0,160 byt 
285 ,840K on disk 
Where: File Server: We-B-Nets in 
joon, NEESREUS 


Kind: Spooler iitggSez sday, September 29, 1988 4: 


> ¢< 
reated: Mon, 


o- a2 


Another way to speeifi_yo is to click iw-theicdn area of the backup and 
restore set like you would a button control. This will switch the volume’s 
icon to the next one in the list. Depending on the number of mounted 
volumes and devices, this may or may not be better than the click and drag 
method described above. 


The example shown above specifies the Server Spooler volume “Tennis” as 
the destination of the backup. If the set was subsequently saved, the new 
destination volume will be saved with that set. 
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Backup Set - “Untitled 1” 


Method: Incremental Append Filter: All Files 
Time: No Automatic Time Specified 
List: 


Thursday, 
SIK folder Monday, September 12, 1988 9:20 
& fone 10K application Saturday, February 5, 1988 12:10 


D fone.p 31K document Thursday, March 24, 1988 5:22 P 
<& Futon Test Application application Friday, May 27,1988 3:06 PM 


de 


Initially, the source volume is displayed as a sirgle entry inthe f le/ folder list. 
By double clicking oh thet éntry, thewolume displays the’nexylevel in the file 
hierarchy. Additionally, t} i tory contents cgn be Aisplayed at once 
by holding down the-@gtion Key\and dobble clicking’on a folder or volume 

entry. (see Figure 2-]s- 


The size and locatioy 
column header area 0 
column width to be changed, and clicking in the inner area allows the 
column to be moved. Figure 2-14 below illustrates moving the Size column 
to the right of the Kind column. 


be changed by flicking in the 


19,680K Local Disk Thursday, 
41K folder Monday , Seg 
10K application Saturday , F 
31K document Thursday, 
18K application Friday, May >| 


8s 
Srsst 
ste 


asete 
oeess 


Figure 2-14 : Moving Column Headers 
Backing up AppleShare volumes automatically saves the user and group 


information for folder's to which the user has access. Subsequently, the 
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restore operation will automatically restore the user and group information 
when restoring to AppleShare volumes. 


2.5.1.2 Restore Sets 
Restore Sets (Figure 2-15) are similar in appearance and function to Backup 


Sets, but they can only view source volume files and folders that actually 
have been backed up to it. 


B) 


Restore Set — AD" = 


NN 


Wfgust 24,1988 1:00 A 
August 29,1988 1:00 4 


Specifying the source and destination volumes for restore sets is the same as 
backup sets. As the source (which the files and folder are restored from) is 
specified, the list area fills with the volumes that have been backed up 
previously. 


Grayed volumes indicate volumes, files, or folders that have been archived by 
the administrator application. If one of the grayed entries was present in the 
list when a restore process begins, a message is generated automatically to the 
administrator. The user will, in turn, see an alert message (Figure 2-16) 
notifying him of possible delays. 
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Some files on “Leia” are not immediately 
available. A message has been sent to the 
administrator. Do you want to Wait for them 


or Continue the operation without them? 


Figure 2-16 : Unavailable Files Alert 


He can either wait until the files become available or continue with the 
restore without the unavailable files (Figure 2-17). 


Figure 2-15 displays an example of three volumes that have been backed up to 
the Tennis Server Spooler volume. If the user wanted to restore the volume 
known as HD, the user would select (by clicking in the file list) and remove 
(via the Cut command in the Edit menu) the entries HD2 and Leia and click 
the Start Restore button (as in Figure 2-18). 


Restore Set - “HD” 


Method: Incremental Append Filter: All Files 


Figure 2-18 : Starting a Restore Operation 
At the start of the restore operation, it immediately checks the destination 
volume, and if the size is a fixed size, determines whether the restore 
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operation can actually take place. Appropriate warning dialogs, such as Figure 
2-19, are displayed if there is not enough room to complete the operation. _ 


There isn't enough space on the destination 
volume to complete the operation. 


Please remove some files from the file 
list or choose a different destination. 
(additional 124K bytes needed) 


Figure 2-19 : Not Enough Space Alert 


An appropriate status message will be displayed in the status window until 
the operation complete 


2.5.2 Workstation Me 


Macintosh 
ng the set currently 


The @ menu is just as in most4 
applications. The staffdard set of menu items rep 
installed desk acte eee is present ks usual. 


f<« isfait_Fitey onyhos_wiowy 
About Ca in... = | 


Prrrvrrrrrrrorio 


Access Privileges 
Calculator 
Chooser 

Control Panel 


About Calvin... displays an about window which provides information 
about the application. A help facility is provided in this window. 
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Orr ry el 


Save Ais... 
Revert to Saved 
Open Messages Log 
Choose Remote Admin... 
Add Spooler... 
Page Setup... 
Print... 


AOS ones ceccecoerceceseeeosareoreense ren somesocegcoaaceseeameonocesaceconccocsnsssonese 


Quit 


New... displays a form & ich allows 
, é saved to the 


startup volume, and are oder” in the 


startup volume's an ae 


© Restore 


i Oaify Backup 
fy 4D 

i friday Backup 
iS MPW Backup 
MS Uatitted 


Cancel 


Name Set as: 


Figure 2-20 : New Set Dialog 
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Open.. . displays a form of the standard file dialog, in Figure 2-20, which 
allows opening of both backup and restore sets. The dialog only lists backup 
and restore sets indicated by the corresponding backup or restore radio button. 


open @BAckuP cor: 


~~ €)Restore 


® Daily Backup 
DB HD 
Q Friday Backup 
CG MPW Backup 

CQ Untitled 


Close closes a 
window has been cha og will be di askjAg whether or not to 


saved, such as the i : fre Widow menu about 
showing windgw / Note that clicking the 
close box on a e Close command. 


startup volume. This menu item is disabled when no Gee exist or there 
is no set window in front. 


Save As... displays a standard file type dialog, Figure 2-22, for the Save 
operation. Backup sets cannot be saved as restore sets and vice-versa. As 
with the Save operation, sets can only be saved to the startup volume. 
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Save Backup Set: 


Sally Backup 
fy HD 
NS Friday Backup 
NS MPU Backup 

NS Untitled 


<= 


Save Set as: 


Open Messages Logdi i »-23, the curyent hi 
workstation actions afidmessage$ received from agminisyrator. All errors 
j log foy future reference. 


The window is editable ase-prOvide fof a way offdeleting past history. 


Witt 
CL] 


Messages Log 


Backup Set “Daily Backup” started... Tue, Nov 15, 1988 6K> 
Backup Set “Daily Backup ” completed... Tue, Nov 15,1988 7 | 
ww 


Backup Set “Daily Backup” started... Wed, Nov 15, 1988 6 
Backup Set “Daily Backup ” completed... Wed, Nov 15,1988 7 
Backup Set “HD” stopped. 125K needed, 100K free in disk... Fri, Nov 17, 1988 4: 


Figure 2-23 : Messages Log Window 


The messages log is useful for finding out whether a particular backup 
operation completed successfully or track the progress of automatic backups 
occurring on a regular basis. The log begins to remove data posted past 90 
days. This is to prevent the log file from becoming too large. The messages 
log is saved in the same folder as backup and restore sets. 
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Choose Remote Admin... displays a dialog (Figure 2-24) to allow selection 
of backup sets to be used for remote administration of the workstation. 
Initially there is a default set selected, specifying the startup volume as the 
source and any administrator's Server Spooler volume as the destination. 
This is useful to provide for administrator assisted remote backup of 
workstations, without having to install special backup sets on each 
workstation. 


Choose Remote Admin Sets: 


Startup Volume Backup <Default> 
1 Daily Backup 

[] MPW Shell Backup 
& Friday's Backup 


Add Spooler... is equivalent to clicking on the Add Spooler... button in the 
volumes window, and displays the same series of dialogs, as shown in 
Figures 2-10 and 2-11, to allow the adding of Server Spooler volumes into the 
Volumes window. To remove a Server Spooler volume, you must bring the 
Volumes window to the front, select the desired Server Spooler, and click the 
Remove Spooler button. 


Page Setup... displays the standard page setup dialog. 


Print... displays the standard print dialogs and allows printing of frontmost 
windows, including the message logs. 


Quit exits the application, querying first whether to save any changed 
documents. 
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AeOoeeerevecnecevencssrasococaceeneesebaceseecencceesacogsseciooeasoesrasesetaee 


Prrerxrrorr rrr ere een 


View Folder Contents 
Delete Files/Folders 
Format... 
Display List Columns... 
Find... 
Find Next 


each time the Undofmenu\commdnd is i~voked uftil thefentire list of the 


volume is displayed 


Cut removes a file or folder item from the backup/restore file list when a 
backup or restore window is the frontmost otherwise Cut functions normally 
for those windows, dialogs, or desk accessories that have text edit records in 
them. | 


Files manually removed from the volume's file list are saved in the backup 
or restore set. If a source volume is changed in a current backup or restore set, 
information pertaining to files or folders manually cut from the file/folder 
list will be lost. 


Copy, Paste menu items function normally in text edit records & desk 
accessories. 


Select All selects all files and folders in backup and restore set windows. 


View Folder Contents descends into a folder that appears in the list area of 
a backup or restore set. This is equivaient to doubie-clicking on a folder in the 
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list. The selected folder will open and the files and folders within that 
directory displayed. If the folder is already open, the menu item will change 
to Hide Folder Contents and the folder's files and folders will be hidden 
from view in the list. 


Delete Files/Folders allows any selected files and folders in a backup or 
restore set to be deleted permanently from the source volume specified in the 
backup or restore set. A confirmation dialog is displayed, as shown below in 
Figure 2-25, every time this menu item is chosen. 


You are about to permanently delete 
12 files/folders from volume “HD”. 


fire you sure you want to do this? 


size, and indey 
message logs. 


Format: 


Font: 

Avant Garde 
Bookman 
Chicago 


Courier 


Garamond 

Geneva 

Helvetica ae 
| Monaco ~ ~~ iM 


Figure 2-26 : File List Format Dialog 


Display List Columns... displays a dialog as in Figure 2-27 which controls 
which column headers in the file list area of backup and restore sets are 
visible. 
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Name — XX] Last Modified Date 
Xj] Size Creation Date 
CJ Kind \ Backup Date 


Display: 


Figure 2-27 : File List Column Selection Dialog 


Find... displays the dialog shown in Figure 2-26 which allows the ability to 
search for a particular file or folder in the source volume of a backup or 

restore set. Find... only finds and sgleets the first file or folder containing the 
matching characters. 
function is proceeding 


Figure 2-28 : Find Dialog 


Find Next repeats the Find... function again, starting off where the last file 
or folder was found. 


Preferences... displays the dialog in Figure 2-29 which contains global 
preferences for the application. 
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Preferences: 


Append File Delimiter Character: [1] | 
Example: Filename! 


Defaults for Backup? Restore: 


(] Always Verify Writes 
C] Open Folders Automatically 


Untitled 


Default Backup Destination Yolume: 


Delimiter Characte 
in use. The dé 


Open Folders Automatically is an option that controls whether folder 
contents should be viewed automatically. If the checkbox is on, all folders on 
the source volume will be opened displaying the entire directory of the source 
volume, as an example below displays: 


Cs eC ES) 


> HD 19,680K Local Disk 
CD file list 4K document 
CD) file list! 3K document 


€] fone 41K folder 
& fone . 10K application Saturday , 
DC fone.p 31K document Thursday , 
<& Futon Test Application 18K application 


Figure 2-30 : File List Folder Calculations 
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To select the default backup destination volume when a new set is opened or 
when the application is opened initially, click on the icon button. This will 
cycle through the various mounted volumes and devices. 


‘Filter 

/Files changed since last backup 

File Types 
File Colors > 

File Names... 

File Dates... 


Pyrite rior rrr 


The Filter menu allows the creation of a selective file/folder filter for a 
Backup or Restore Set. Each filter selection i is dee to the set and is stored 
in the Set. The Filter t sqnsitivg : +e indow and 


backed up or restored. 


° Filter 


“Files changed sintelast backup 
File Types) 2 All File Types 
File COLTS _—=_—_—_—_—_—_—_—_ fssesseseesseeeernnnnanennnsacerennnnnnereananennannnrsenezancnnnnsseesenannnessee 
File Names... “Control Panel Documents 


File Dates... HyperCard 
alae tas atid cas eslcaaaaanl ahaa eee Necdaipttaaeacabanes MacPaint 
View Current Filter... /“MacWrite 
Microsoft Excel 
System 


Text Files 


ooo ccnesevacesoceccccaseesecs 


Add File Tipes: aces 


File Types displays a hierarchical menu that lists a set of application file 
types. Only those types checked in the menu are actually listed in the file list 
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of the Backup or Restore Set. Choosing a file type item will toggle the check 
_ mark on and off. 


Initially, the application comes with some standard types, but provides the 
ability to modify what types appear in the menu by choosing the Add File 
Types... menu item. A dialog appears (Figure 2-31) which lists all of the 
applications known by the startup volume. 


Add File Types: 


Control Panel Documents ray 
HyperCard ; a 


MacDraw 
MacPaint 


| (req | 
ar 
Doon 


displayed, the file type will added or removed from the menu. File types 
already in the menu are indicated by underlined entries. 


File Types 
File Colors *.--., 

File Names... Pink 
File Dates... Light Blue 
seassnsensensensanscnsencansensencnnencenceucensenceesensacsensoeseuvenucesensacsenvecvesseanesogsnvenssoeesse Dark Blue 
View Current Filter... Green 
Brown 
Black 


File Colors allows the ability to list only files that have been colored via the 
Finder. Initially, the default selection is all colors. 
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File Names... displays the dialog below in Figure 2-32 which allows the 
ability to list files only matching character strings in this dialog. 


File Name Match: 


@ Active © Inactive 


Filter: 


File Date: 


@® Active © Inactive [ oK_ | 


Date: za Time: 


cs 


10/13/88 1240 Pr 
@ 12hr. © 24hr. 


Using: | Modification Date 
@ Later © Earlier 
Figure 2-33 : File Date Filter Dialog 
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The popup menu displays criteria in which to match either dates later or 


earlier. Only files that match criteria in this dialog are displayed in the set file 
list. 


“Modification Date 
Creation Date 
Backup Date 


View Current Filter... displays a dialog in Figure 2-34 that shows the 
current filter criteria for the frontmost backup or restore set. 


Filter Status: 


File Types: 


Match: Partial 


Figure 2-34 : Filter Status Dialog 


Note that this dialog only displays the filter criteria, and does not allow 
editing. 


Calvin & Hobbes ERS 1.0 1988 Apple Computer Inc. - Apple Confidential 
Page 33 12/20/88 


Calvin Backup and Restore Service 


‘Options 
Show Removed Files 
“Calculate Folder Sizes 
“incremental Replace 
Incremental Append 
Entire Backup 
Compress Files 
Encrypt Files 


PPTTTITITTTT TTT 


9 0000000 00000000050 eset eeeesenees caseeonSesesesnressaveneeneseccesoaonoseneee 


HFS Files/Folders 
Partitions 


Method: Incremental Append Filter: All Files 
Time: 1:20:00AM Everyday: Monday, Wednesday, Friday 
List: 25 files/folders 6400K out of 19,680K bytes total 


Cn  ——————— 
Name Size Kind Last Modified 


eer eee nee ere ee ae ee eae eT Oe YO TT SO Re SR VR RE, Sa PP ne ICY in dee a ae aT 
Pigie sail? aie ada Saat isa AG RY TOE TART RT RSS POA ee SOE SR TO ET SR EE a TO SO er ee eae Ces 
ae ier Ther Seen Snee eee See SG ee RG >” Ce ee COU ame es We” OE nt OG 
a oe her ee er ee er ee ee ee ee +? See re ott) @ . Tt ee ee eh ins 
eo 8 @ e eo ee ee 
Ce ee ee i Se Se a Se i 


era rw we te oe we oe wt ee CM AAIIPANTE 1.28. t ete te fe ® 


FE ee Tare aia ae ne ae ee ee a Se a ae eer SP SOT ree Tae TS Te SREY EPR MR, A, PT OP APL ar aR Bee he De eC PONE SO fae DT 
Pane wee See Shee eee Seer Seer Deer meer ©) 2 Weer ee O18 OL"! @ P| 2 8 doe ee De ee ee ee 
Cer Tanda Wand Wey Wide Seat Sia ee RSE Thad dP CO Viel fie Bots bbe a, ee a eee el a 


© fone folder 
& fone 10K application Saturday, February 5, 1988 12:1 


D fone.p 31K document Thursday , March 24, 1988 5:22 P EEE 
<& Futon Test Application application F ‘ew 
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The files with the gray pattern indicate removed files, and can be placed back 
in the list by either double clicking each grayed list entry or by selecting the 
Undo menu command. 


Calculate Folder Sizes is an option which enables calculation of the size 
in bytes of every folder displayed in the file list of the set window. If the 
option is checked in the menu, folder size will be shown in the Size column 
of the list area. This is typically a time consuming operation as each folder 
that is displayed must be completely enumerated. The default for a new set is 
unchecked. 


Incremental Replace, Incremental Append, and Entire Backup are 
options that control how the backup or restore operation is to transfer files 
from the source to the destination volume. The Incremental Replace option 
when enabled causes each matching destination file to be deleted and replaced 
by the source is peroneal Ap pend ee plea new or changed files 
ancfers every file i in 


ed by Calvin in order to 
¥ the file. 


aTr“€ data and writes it out as a 
new file. The file must be restored by the Calvin application as if the file was 
compressed, (by using the Compress Files option) in order for the file to be 
opened again. 


Set Automatic Time... displays the dialog in Figure 2-36, which allows the 
automatic timed execution of a selected backup set. 
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Set Backup Time; Backup Set - “Daily Backup” 


@® Active © Inactive 


Time: Q 1:24:32] pm a 


® Recurring © One Time Only 


Days: Monday Date: [aT] 
(CJ Tuesday 
J] Wednesday 10/13/88 
(Thursday 


[X] Friday : 


CJ Saturday 


To use this option, sdlec 
backup a set on a reg 


e of day. To 
tton and select the 


and enter the date. 


The HFS Files/Folders and Partitions menu options toggle between using 
standard Macintosh HFS files and partitions on volumes. When the 
Partitions menu command is selected, the file list of the source volume will 
change to a partition list. The user can then select which partitions will be 
either backed up or restored. 
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Window 


Tile Windows 
Stack Windows 


Status 
Volumes 
“Backup Set “Daily Backup” 


The Window menu provides two commands: Tile Windows and Stack 
Windows which will arrange visible windows into a tile format or stack all 
windows. All other entries in this menu correspond to windows that are 
either open or can be opened by the application. 
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2.6 Administrator 


The administrator application is a superset of the workstation application as it 
contains all of the workstation functionality of backing up or restoring any 
volume, along with providing the routines necessary to create and setup 
Server Spooler volumes. 


Server Spooler volumes are actually AppleShare volumes with a special set 
of files and folders installed and a special network naming routine that 
registers the AppleShare volume on the network with a specific Server 
Spooler type so that workstations can identify the Server Spooler on the 
network as a special form of an AppleShare volume. 


The administrator application contains routines to send and receive messages 
between workstations, get the messages log of any workstation user on the 
network, and initiate remote backups of any workstation. 


Every time the admipi 


Spooler and, in tur 
Add Evidence... and 
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2.6.1 Administrator Flow 
2.6.1.1 Status Window 


Once a Server Spooler has been setup, the administrator application keeps 
track and displays the currently selected Server Spooler in the status window 
(Figure 2-37). 


Calvin Administrator: “SuperUser” 


ei tcletete tat ate te Sate te tete tree te tee 
ol aletet eto tes ete setete sete atatetetate 
ESSeSEtI SPECI Shei ee erste steely 


Version 


Set: 
“Daily Backup ~ 


In Progress 


"In Progress 


The administrator application controls only one Server Spooler at a time. A 
new Server Spooler can be chosen by dragging from the Volumes window 
similarly as when specifying a source or destination volume in a backup or 
restore set. If the Server Spooler is not present in the Volumes window list, 
choose Add Spooler... from the Edit menu or click the Add Spooler... button 
in the Volumes window. 


2.6.1.2 Monitoring 


If it is anticipated that Server Spooler space problems may occur while the 
administrator is away from the machine (e.g. at night), the administrator can 
go into a monitoring mode where the automatic smart download feature of 
Calvin can be activated. This feature, available through the Admin menu, 
constantly monitors Server Spooler space requirements. If additional space is 
required on the spooler, this download feature will copy and remove files 


Calvin & Hobbes ERS 1.0 1988 Apple Computer Inc. - Apple Confidential 
Page 39 12/20/88 


Calvin Backup and Restore Service 


from the Server Spooler to the administrator's requested local device media, 
updating user’s Evidence files as necessary. 


2.6.2 Administrator Menus 


The administrator portion of Calvin is a superset of the workstation 
application in that it provides an additional menu called Admin for setup 
and other functionality related to the utilization of Server Spooler volume 
services. 


The @ menu for the administrator application is present in Calvin just as in 
most other Macintosh applications. The standard set of menu items 
representing the set of currently installed desk accessories is present as usual. 


| [PS File Edit Filter Options 
About Calvin Admin... 
Access Privileg 
Calculator 
Chooser 
Control Panel 


Window Admin 


ixfiow which/p Ps information about 
the Calvin administrator application. A help facility is provided and will 
display information in a topical list including text and graphics. 


The administrator application is a superset of the workstation application, 
and the menus File, Edit, Filter, Options, and Window operate similarly. 


The Admin menu provides the needed controls to perform various 
administrator functions such as setup of the Server Spooler or performing a 
workstation remote backup. 
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Setup Spooler... 
User Status/Messages... 
Remote Backups... 


|e Weeeee enone merecrenserennccereenesecerereoeeseeensresersncossassececececneceareooeseeeceCese 


Pree rrr rr rere rr rere 


Add Evidence... 
Remove Evidence... 
Scan Evidence Files... 
Print Evidence Files... 


Setup Spooler... 


This command] invokes a series of dialq pgs below igure 2-38, 2-39) to enable 
an AppleShare se : | orSpoofer volume by 


Initially, the A and fhe dialog in Figure 2- 
38 is displayed. 


zs Marquee oy 
“A DataFile _ 
on We-B-Nets.-" UE 

v7 


Password: 


Gl Nets-R-Us < 
C] Twlight Zone 


Figure 2-38 : Server Connection Dialog 


First a Zone is chosen, which then displays a list of AppleShare servers on the 
network. Note that both AppleShare volumes and volumes which have 
been setup to be Server Spooler volumes will be displayed in the server list. 
Select the desired AppleShare server, enter a user name and password and 
click the OK button. If the log on is successful, the dialog in Figure 2-39 will 


Calvin & Hobbes ERS 1.0 1988 Apple Computer Inc. - Apple Confidential 
Page 41 12/20/88 


Calvin Backup and Restore Service 


appear requesting that the user select a volume, entering a volume password 
if necessary. Volumes which are Server Spooler volumes show up with a 


mini spooler icon. 


Volume Name: 


©) BananafFish fe, 


ray 
‘8 Tennis. - Qo } 
| 


Passion [ OK | 
"eneel 


Server Spooler volumke * d 
volume to be selected_as a Server Bpooler) For the sftup, the group that each 


of the users of the stad restorg services is entergd at this time. 


Volume “BananafFish" has not been previously 
setup for Backup and Restore operation. 
To setup volume, enter an AppleShare group 


name and click Setup. 


(Gor ] 


Figure 2-40 : Server Spooler Setup Dialog 
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If the selected volume was previously setup for backup/restore use, a 
different dialog is displayed (Figure 2-41) allowing the reinstallation of the 
administration files and folders. 


“vy, Volume “Tennis” is already setup for Backup 
> and Restore. 


To change or initialize previous setup, click 


initialize. 


= 


Figure 2-41 : Reinitializing Server Spooler Volume Alert 


the Initialize 


= 


Figure 2-42 : Last Warning Alert 


The spooler can be cleared of the backup services by manually deleting the 
Calvin folder from the AppleShare volume. 


User Status/Messages... 


This displays a dialog (Figure 2-43) which always displays current information 
and status about users of the Server Spooler. The administrator info file on 
the Server Spooler is opened and all pending messages that have been 
generated by the workstations, if any, are indicated in the user list. Messages 
include errors and requests to restore files to the Server Spooler volume. 
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User Status/ Messages: 


User Status Messages 


Restore 
Offline 


| Get User Messages | Get Workstation Log 


Message to Send: 


Each user's current stat Mf to the right a 


workstation Messages log is displayed if the 'Get Workstation Log’ button is 
clicked. 


Messages Log of “Bill” 
Message Date 


Backup Set “Daily Backup ” started... Tue, Nov 15, 1988 6: 
Backup Set “Daily Backup ” completed... Tue, Nov 15,1988 7: 
Backup Set “Daily Backup ” started... Wed, Nov 15, 1988 6 
Backup Set “Daily Backup ” completed... Wed, Nov 15,1988 7 


94900094947-494947-091 7 ee Pe Pee eee) 


sete t eel eset eset esate ose sesete esate sas ese sec eteses ese lec ese sey 


Figure 2-44 : User Messages Log Window 


This log allows the administrator to monitor the state of each user of each 
Server Spooler, and for example: check if each workstation is or has been 
backing up files on a regular basis. 
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By clicking the 'Get User Messages’ button or double clicking on an user entry 
displays a window, as below, that lists messages from all users. 


User Messages 


Message Date 


Bill: Please restore “Tape 2” of “Daily Backup ” Tue, Nov 15, 1988 61>] 


Figure 2-45 : All User Messages Window 


Remote Backups... 


Choose Set(s): 


Startup Volume <Default> 


DailyBackup | 


Figure 2-46 : Remote Backup Set Selection 
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The workstation user has an option to disabled this function by not selecting 
any backup sets. These users will be shown in gray. 


The default set for the workstation is always a backup set that has the startup 
volume specified as the source and the administrator's current Server 
Spooler as the destination. The default set always backs up files in an 
incremental fashion, and includes every file on the volume. 


Select the user and the user's backup set(s), and click the Backup button. If 
any of these backup sets are timed backups, this will override the time and 
start the backup immediately. 


Enter Monitoring Mode... 


If the administrator will be away from his system for an extended period of 
time, this command places the application in a monitoring state where the 
Server Spooler space will be conctane monitored Oh administrator will see 
2 a = aused for 
storing information. by clicking on tile devyce area, the various devices will 
, medal—yei-sa drag a 


Free Space: 118,000K 
Used Space: 
Percent Used: 


Status: Stopped 


(Geet) Ger) Cancer) 


; Figure 2-47 : Entering the Monitoring Device 


Media contained in this device will first be initialized, renamed (through an 
unshown dialog) and then the monitoring will begin. The dialog (Figure 2- 
48) will change to show additional monitoring status and information for the 
device. 
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Monitoring “Tennis": 


Destination: 
Monitor *1 


Free Space: 118,000K 
Used Space: 129K 
Percent Used: 1% 


Status: Waiting... 


archive informatiotm= : ited, the Ad Evidence and Remove Evidence 
commands can be used. Here are some ae 


e The administrator wishes to give User A's file to User B and 
User C. Just use the Add Evidence command to add evidence 
information to both User B's and User C’s evidence files. 


° User A leaves the company and all his files are to be given to 
User B. You would use Add Evidence to copy all evidence 
information from User A to User B, and then you would 


‘delete User A's evidence by using the Remove Evidence 
command. 


¢ The administrator loses User A's archive Tape #2. You could 
Remove Evidence of Tape #2 so User A would not think he 
still had access to those files. 


Both of these commands are menu items that control what files will be 
visible to the workstation application when viewing the Server Spooler. 
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Both menu items, when chosen from the Admin menu displays the dialog in 
Figure 2-50, asking what user to add or remove evidence: 


Add/Remove Evidence: 
Choose User: 


entries from that media 
folders displayed in 


up from a spooler, | 
removed from the 


CHD 19,680K Disk Thursday , September 29, 198842 
( MPY Shell 8 ,100K Folder Thursday , September 29, al 
wa 


(1) Good Stuff -~. so 11,559K- Folder = ~* Thursday, Septernber 29, 198 
& Documents 41K Folder Monday , September 12, 1988 

& fone 10K Application Saturday, February 5, 1988 1 
D) fone.p 31K Document Thursday , March 24, 1988 5: 
19 ,680K Disk Thursday , September 29, 198 


& 


Figure 2-51 : Add Evidence File List Selection 
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The administrator can remove (cut) files from the Add Evidence... list in the 
same way the files can be removed from a backup or restore set. By clicking 
the Add Evidence button, the Evidence file for the user is updated and the 
contents are now available (visible) from the workstation. Note that the files 
and folders will appear grayed in the list until the administrator actually 
restores the files to the Server Spooler. : 


Remove Evidence... 


After choosing a user, a window appears (Figure 2-52) that lists the volumes, 
files, and folders already in the user's Evidence File on the Server Spooler. 
Any entry can be removed manually in the same way as removing files in a 
Backup or Restore Set. 


Evidence List for “Bill” 


{J Good Stuff - 11,533K°  -‘Tipes 2-3” i Thursday , September 29,1992 
Monday , September 12, 1988 
Saturday, February 5, 1988 1 
Thursday , March 24, 1988 5: 


comm ay ee — 1-3 i September 29, 1988 -sday , September 29, 1984 
(© MP Shell 3,19 OK ape 1 hursday , September 29, =e 


Figure 2-52 : Remove Evidence File List 


Clicking the Remove Evidence button will remove the files and folders listed 
in the Evidence List from the user's Evidence File stored on the Server 
Spooler. This action prevents the user from viewing those files or folders as 
part of the Server Spooler. restore set. At first glance, this may seem awkward 
since the administrator is cutting away files that will not be removed in the 
user's Evidence File; instead they are preserved, but it follows the same user 


interface which is in use throughout the application. 


By carefully using the Add and Remove Evidence commands, the 
administrator can control which files are available to which user and can 
actually allow other users to restore files that were originally placed on the 
Server Spooler by another user. Remember though, that the administrator 
only changes evidence information. The files are kept on their respective 
archive media. 
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Scan Evidence... 


This menu command displays a window, as below in Figure 2-53, that allows 
the administrator to scan a specific backup media or volume and see if any 
Server Spooler user has links to that media. What this provides is a utility to 
enable the administrator to tell if a media is no longer pointed to by a user's 
Evidence File so that the media can be reused. Without this command, the 
administrator would have to search each user's Evidence files by performing 
a Remove Evidence... command and then searching this user's Evidence list 
for a specific media reference. 


Scan Evidence Files... 


rf the Evidence files 
found will be opened and 6s and folders compared with the specified 
source media If any match is found, the corresponding user name will be 
added to the list area of the Scan Evidence Files... window. 


Print Evidence Files... 
This command enablés: the administrator to know what Evidence 


information is available to a selected user of the Server Spooler. A dialog is 
displayed (Figure 2-54) when the command is chosen from the Admin menu. 
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Print Evidence Files: 


Choose User: 


Figure 2-54 : Print Evidence User Selection Dialog 


Select user(s) and click the Print button to print the Evidence file information 
for each user. . 
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3.0 Software Distribution (Hobbes C3 


3.1 Overview 


Hobbes provides a simple, but efficient automatic software distribution and 
updating service. Its purpose is to distribute new software and to ensure that 
software on a user's system is the latest available. 


The software distribution system consists of workstation agent, an 
administrator agent and an AppleShare server. Any existing AppleShare 
server can be used and space is claimed dynamically on the server volume 
ensuring full utilization of the disk. Unlike Calvin, there is no “local-only" 
mode. All pieces are required to use Hobbes. . 


AppleShare adminis 
administrator. 


A quick note about virus infections. Since all software distribution folders are 
write protected, the only way a virus can infect a user's local volume is to be 
already contained in the software before it is installed onto the server by the 
administrator. The documentation should instruct the administrator to 
check sorware before e placing it onto the server. 


3.2 Architecture 


The software distribution system consists of one or more workstation agents, 
an AppleShare server and an administration agent. Each of these agents 
reside as a separate process in the system, however nothing prevents one or 
more agent from residing in the same system. In fact, it is likely that the 
administrator's system will contain both AppleShare and the software 
distribution administrator agent software. The administration agent does not 
need to be online in order for the workstation to access its software. 
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Workstation [> / AppleShare 
Agent | oe Server 


Neon Lights 


pn, 
i O 


Server Folder Calvin & Hobbes 


= 


Calvin 


om 

Scripts 

pa ae 
O D 


MacPaint Seript System Script MacPaint Folder System Folder 


a x & 


MacPaint 2.0 System CDEVs 
Figure 3-2 : AppleShare Server Volume Directory 
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In order to speed up the implementation process, a standard AppleShare 
server is used for script and file storage. One directory in the root of the 
server volume ("Calvin & Hobbes") will be dedicated for use by both the 
software backup service (Calvin) and the software distribution service 
(Hobbes). For the software distribution system, a folder called "Hobbes" 
contains scripts and the script file folders. (Figure 3-2). These folders are | 
available read-only to the users; the administrator is the owner of the folders 
and has complete access to them. 


3.3 Feature List 


Automatic Notification Of New Software 
Automatic Updates 
Local or Remote Administration 

Quick Scan Capability. 

Simple to Install, pple to oe 


eae AppleSha 
MultiFinder Ca 


3.4 SetUp 


° Set up the Apple 
® Install workstation ee on all workstations 
e Install administrator software on the administrators machine. 


3.4.1 ie up the e AppleShare Server 


The AppleShare server is an integral part of the software distribution system. 
If an existing AppleShare server cannot be used as the software distribution 
server, the administrator must set one up. For ease of administration, both 
the software distribution administrator and the AppleShare administrator 
should be the same individual. Unlike the backup service, the administrator 
does not need to be a cc areal of the server. 


Once the AppleShare server is up and running, the administrator should run 
the AppleShare Admin application and set up one or more groups for use by 
software distribution. Each user of the software distribution system must be a 
registered user on the server and belong to one of these groups. Each script 
can have only one group associated with it. For examples used in this 
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document, the group "Hobbes Group” is used to represent the standard 
software distribution group. 


If the administrator wishes to hide scripts from some users, additional 


security can be obtained by setting up specific groups for specific update scripts. 
The administrator can assign these groups to various scripts. 


Hobbes Group 


Hobbes Group, PageMaker Group 
Hobbes Group, PageMaker Group, C++ Group 
Other Group 


Example 1 


For example, in the list above, Joe, Bill, and Frank all belong to the Hobbes 
Group. They woud nave access to most EOF the software distribution scripts. 
viekeer ei dee while 


3.4.2 Workstation Installation 


The workstation installation consists of two files; the workstation application 
"WKS Updates" and a combination INIT and script storage file called "WKS 
Update hae 


The WKS Updates spplicaton can be sis anywhere on the user's disk. 
Since it is AppleShare friendly, it can even be a multi-launch application on a 
server volume: . 


The WKS Update P Prep file must be in the users system folder. It contains the 
INIT code for handling system startup update checks as well as names of 
currently active update scripts. 
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3.4.3 Administration Installation 


Like the workstation installation, the administration installation contains 
two files. These are called "Admin Updates" and "Admin Update Prep". The 
locations of these two files follow the same rules as the workstation’s files. 


3.5 Workstation 
3.5.1 Workstation Flow 


The workstation application is used primarily to activate scripts and set up 
their destination directories. Most of the time the actual updating will be 
done automatically at system startup time, although the updating can also be 
done from within the application itself. > 


Upon executing the workstation application, the user is presented with the 
menu bar. The user peleets-the-Server /Connget-men pmmandto log onto a 
3 ing the zone 


names. The user then s@le a 
appear. Next, the user splects-a-se ais user na 
that server and finally clic 


OS Ty Ty 


Server Zone: 


(_\ 


A Nets-R-Us 


maa | 
| 


Nome Coy 


Figure 3-3 : Selecting an Update Server 


If the log on is successful, another dialog (Figure 3-4) appears showing the 
update server volumes. Only volumes which have been set up by the 
software distribution administrator will appear. The user selects a volume 
and, if necessary, types in the volume password. Finally the user clicks the 
OK button. 
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Server Name: 


Volume Name: | 
Xt Neon Lights a 


x84 


Server Zone: 


Name: 


r 


Password 


C] AppleLink | 
Kk Excel | 4 350K 
CO] FileMaker 15 729K 
K] Font/DA Mover | 37K 
OO Lotus 1-2-3 3 240K 
| & MacPaint 4 385K 
“| &] MacTerminal 3 190K 
i) Macwrite 5 103K 
& PixelPaint 9 1,239K 
K Word 


Figure 3-5 : Script List Window 


The window list contains script entries set up by the administrator. Each 
entry contains: 


1) A status check box indicating whether or not this script is 
active for this user. 
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2) The script's name 
3) The total number of items in the script - both files and folders 
4) The total size (in kilobytes) of all items. 


Only scripts which the user has access to will be displayed. The user can 
rearrange the view by selecting appropriate options in the View menu. If the 
user wishes to edit or just look at a specific script's information, he can either 
double click on that script's line or select it and choose the Open Script menu 
command. This brings up the script information window (Figure 3-6). 


Status: @Active © Inactive 
KK] Notify me before updating 
Files: 5 Folders: 1 Changed: 1 Size: 783K 


Figure 3-6 : Script Information Window 


The user can then make changes to the active status or change the destination 
location. If the "Notify me before updating" check box is selected, pending 
updates will cause a dialog to appear right before the update occurs. If the 
check box is off, no dialog appears and the update occurs immediately. This 
can be useful in systems which have no monitor or keyboard (e.g. Routers). 


Files either changed since the user last updated or are new are shown in bold. 
The user may wish to use the Get File/Folder Info... menu command to check 
on file information..- 3 


When the user is done editing the script, he can either click on the close box 
of the script's window or choose the Close menu command. If changes were 
made, a save dialog will appear asking if the user wishes to save those 


changes. If he decides to save them, the information will be written out to 
the main file. 
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To initiate an update, the user can choose one of the two update commands 
in the Update menu: Quick Scan or Complete Scan. Since updates occur 
automatically at system startup time, this is only necessary if the user requires 
the update immediately. Quick Scan will do a scan of the active update 
scripts, looking only for changes made recently by the administrator. . 
Complete Scan will initiate all active scripts ensuring the user that the 
software on the user's system is the latest. | 


The workstation may also receive an update notification directly from the 
administrator. When the administrator is finished with a script change, his 
application will look for all software distribution workstations. If the changed 
script is active for that workstation, an alert will appear on that user's system. 


If, either after initiating a scan or by an administrator change, the application 
detects that an update is required, an alert appears (Figure 3-7). 


The user can choose to do the update immediately by clicking the Yes button. 
If not, it can either be ignored by clicking on the No button or postponed until 
the next time a scan takes place. Note that if you click on the No button, the 
only way to update later is to choose the Complete Scan menu command. _ 


When the user has finished, he selects the Quit command. If information 
needs to be saved, an appropriate save dialog appears and the information is 
written out to the file. The update system is now active. 


At system startup time, a quick check is made to see if any active scripts 
require their files to be updated. The algorithm followed is the same one as 
the Quick Scan menu command in the workstation. If an update needs to be 
made, the same dialog appears as in Figure 3-7. 
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3.5.2 Workstation Menus 


a File Edit Options View 
About Epuee. WKS... 

Alarm Clock 
Calculator 
Chooser 
Control Panel 
Find File 
Key Caps 
Scrapbook 


S00 cea cuocccos: 


About Hobbes WKS... 


The About command¢ wenkstation 


Open Script 


If a selection is made in the server volume's script list, the Open Script 
command opens a window for that script as was shown in Figure 3-6. As 
mentioned earlier, information in the window includes the status of the 
script, a notification flag, and information about pk files and tone which 
belong to the script. 3 


The "Status" buttons indicate whether or not this script is active. If the 
Inactive radio button is selected, no updates will occur for this script. The 
"Notify me before updating” check box is a flag which indicates if an alert 
should be displayed when an update needs to occur. If this check box is not 
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selected, this script will be updated automatically. This is useful for systems 
which may have no user interface (e.g. AppleShare servers or bridges). The 
number of total files, folders and the number of files changed are shown on 
the following line along with the total size of all items. The "Script Last 
Updated" line tells when the script was last updated by the administrator. 


The pop up menu (Figure 3-8) describes the destination path which will be 
used to store the folder'’s contents. Like the standard file dialog's pop up, it 
shows the path back to the root of the volume, however it does not allow you 
to alter the path using the pop up. Instead, the user will have to choose the 
"Set Script Destination..." menu command under the Options menu. 


©) Word 
Applications 


Ho HORReS 
Figure 3-8 : Script Jafermation Window Pop Up Menu 


Under the pop pa menu is the fil b list fc r this script. It is viey ed in an 


- Close menu command 


If the front window is a script list, this command would log the user off of the 
server and close all windows associated with that server volume. 


Save 


Save saves , the current state of. a ai to the main file without closing the 
window or dialog. — 


Page Setup..., Print... 
These commands bring up the standard print dialog boxes. 


The Print command will either print the a volume's script list or a script's file 
information depending on the window currently in front. 


Calvin & Hobbes ERS 1.0 1988 Apple Computer Inc. - Apple Confidential 
Page 61 12/20/88 


Hobbes Software Distribution Service 


Quit 


Exits the application, asking the user to save any changes made. 


Server Connect 
Get File/Folder 
Set Script Desti 


Server Connect... 


This command is used to connect to a software distribution server using a 
Chooser-like mechanism. When chosen, the dialog in Figure 3-3 appears 
allowing the user to select the zone and server name. (Note that only servers 
and volumes which have been set up by the administrator will show up in 
the server name list.) Next the user enters his user name for that server and 
his password. Guest log on is not supported by this application. Finally the 
OK button would be pressed to confirm the user's identity. If the user logs on 
successfully, the volume selection dialog (Figure 3-4) appears. 


If there is no volume password, that field is grayed (we may decide to hide it 
completely from the user). The user then selects a server volume and clicks 
OK. If everything goes well, the script list window for this volume would 
appear. = eee ee eg, © oe ae 
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Get File/Folder Info... 


This command is available only if the user has a script information window 
open and has selected a file or folder in the list. It brings up a window 
(Figure 3-9) containing information about the file or folder. 


SS File/Folder Info 


Main Dictionary 


Kind: Word 3.01 document 
Size: 164.824 bytes used. 161K on disk 
Created: Sat, Jan 31, 1987,6:01 AM 
Modified: Sat, Jan 31, 1987, 6:01 AM 
Version: not available 


Figure 3-9 : File/Folder Information Window 


Set Script Delstination... | 


standard file dij 
are to be placed: 


Search All 
If this menu itenti 


mounted volumes for updates instead of just the script s selected destination 
volume. 


All — 


FON O0 O80 060 B00 C0 FEDS CCT ESSE CODE COS DES OOS 280 SEDeTORROTCORORES LES OEE RESCOEESEOLESEOR 


actus Scripts 
New Scripts 


The View menu allows the user to specify which scripts will be shown in the 
script list. All Scripts specify exactly what it says: all scripts will be shown. 
The user also has the capability of showing a subset of the scripts. This 
currently includes active or new scripts. 
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Update 
Quick Scan 
Complete Scan 


Quick Scan 


This command does a manual scan of last modification dates on any active 
scripts to see if any files need to be updated. This is only necessary if the user 
suspects that a modification was made to the scripts by the administrator after 
the user last started up his system or if the user has just made a script active. 


If no updates are needed, under normal circumstances this command should 
only take a short time to execute. | 


Complete Scan 


al executes 
anual 
Ywants to be 


The poe aaa Scan cemmend- 


A status dialog igre 3 3-10) appears allowing the user to terminate the 
operation by ae on the Cancel button. 
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3.6 Administration 
3.6.1 Administration Flow 
After starting up the administrator application, the menu bar is aipreeeniad. 


The administrator chooses the Server Connect menu which brings up the ~ 
server connection dialog (Figure 3-11): 


SS Zone: Server Name: 


ch Marquee 
G3 Nets-R-Us — a2 DataFile 


o2 We-B-Nets 
ios eee 


Ci Twilight Zone 


connect dialog only showed the servers who had already been set up by the 
administrator.) 


The administrator chooses a server, enters his superuser name and password 
and then clicks on the OK button. If the log on succeeds, the volume 
selection dialog appears (Figure 3-12): 
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Server Zone: Server Name: 


Volume Name: 


$ Bananafish 


_¥ Neon Lights : 


Passwore 


This volume has not been set up for Software 
“s Updating. If you wish to set it up, enter the 
AppleShare group name and then click OK. 


Figure 3-13 : Volume Not Set Up Alert 
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If the administrator decides to set this volume up, he types in the group name 
to be used by this volume and then clicks on the OK button. If this volume is 
not to be used, the Cancel button can be clicked to exit and log off the server. 


After a successful log oy the administrator’ S eel list window 1 is ue ciepiyes 
(Figure 3-14). ; e an a : | 


a ee on “Neon Lights "=== 


Items 


Size 


AppleLink 2.0 
Excel 1.5 4 350K 
FileMaker 3.0 15 729K 
Font/DA Mover 3.4 37K 
Lotus 1-2-3 


its total size. 


3.6.2 Administratte 


a File Edit Script 
About Hobbes Rdmin... 
Alarm Clock 

Calculator 

Chooser 

Control Panel 

Find File 
Key Caps 
Scrapbook 


Options 


About Hobbes Admin... 


The About menu command displays the name and version of the program. 
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Save As... 
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This name is used by the application to create a folder on the server volume. 
After clicking on the OK button, the script will automatically be opened (a la 


Open Script). 


Open Script - 


Once the administrator selects a script name from the script list, this 
command will open a window (Figure 3-16) and display that script's 


information: __ 
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ResEdit 


Server Zone: We-B-Nets 
Server Name: Marquee 
Server Yolume: Neon Lights 


©) ResEdit 2.0 


& ResEdit 
© ResEdit Templates 
O Templates 


workstations, the gerver location and aj lis} ilesAssq hated with the 
script. | 


Figure 3-17 : capt Window Pop Up Menu 


The pop up menu (Figure 3-17) shows the destination to the script files on the 
server. Like earlier pop ups, this one only shows the path. The administrator 
cannot change it without choosing the appropriate menu command. 


Close a 

The Close menu command closes a window. If any changes were made, a 
standard save dialog will appear, asking the user if he wishes to save the 
changes. Note that the close box in any window operates the same as the 
Close menu command. 


If the front window is a script list, this command will remove the window 
and log the administrator off the server. 
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Save, Save As... 
Save saves the current state of a script to the file without closing the window 


or dialog. Save As will bring up a small dialog, permitting the administrator 
to save the script under a different name. 


Page Setup..., Print... 
These commands bring up the standard print dialog boxes. 


The Print command will either print the a volume's script list or a script's file 
information depending on the window currently in front. 


Quit 


Exits the application, asking the user to save any changes made. 


All Edit commands follow Standard Macintosh user interface guidelines. 


Script 
Get File/Folder Info... 
Set Destination... 


000 886 S00 CEG Cees LE COsSs DON C00 SEs CES ROOD OSREOSEOD. 
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Copy Files... 
Select Files... 
Options... 


Get File/Folder Info... 


If the administrator selects a file or folder object in a list, this menu command 
will display a small window (Figure 3-9) containing information about that 
object. This command works exactly the same for both workstation and 
administration applications. 
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Set Destination... 


This command brings up a dialog (Figure 3-18), allowing the administrator to 
change the location of the script file's directory. It also can be used to remove 
unlinked script directories (see below). All script directories are kept on the 
server. The administrator can add a new empty directory by typing in its 
name and clicking on the Add button. To select a directory, select it's name in 
the list and click on the OK button. 


Set Destination: 


Please choose the script file's per ony 


OO Applelink 2.0 
Dem eae 


least one script is creedy associated with the Se ete If the 
double arrow is missing, the directory is unlinked. Unlinked directories can 
be deleted with the Remove button. Linked directories can only be deleted by 
opening it's associated script and then using the Delete Script menu 
command. : 


Copy Files... 

The Copy Files command is used to copy objects (file or folder) to the server 
volume. A dialog appears (Figure 3-19) containing two lists; one is a standard 
file-like list which allows you to select a source object. To copy the object to 
the script's server folder, select it and click on the Add button. The object will 
immediately be copied to the script's folder. 
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CO Macsbug 
01 Macsbug Templates. — 
© Templates 


When finished, click on the Done button. 
Select Files... 


Select Files allows the administrator to select a subset of files in the script's 
folder for use by this script. A dialog appears (Figure 3-20) which displays a 
list of the files currently ‘in the script's server folder. By selecting files or 


folders, you can choose which files will be linked to the script. 


Calvin & Hobbes ERS 1.0 1988 Apple Computer Inc. - Apple Confidential 
Page 72 12/20/88 


Hobbes Software Distribution Service 


Select Files: 


XX) & ResEdit 

] € ResEdit Templates 
CJ) OD Templates 

& O More Templates 


Each script can be grouped into one of three script types: Application, General 
or Installer. Each script type may have its own specific options. 


Sp, 
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Script Options 


Script 
Type: 


- Group: |Hobbes Group 


@ Application © Installer © General 


Copy: @Everything 
© Application Only 


Use: @Application's Creation Date 
© Application's Last Modification Date 


This script type is uged i theiy/associated files. 
The administrator copies these fil es into he script ff der sing the Files 


copy in the user's scripMtest#natta directory, t apptication and its files will 
be installed there. = 


Two flags are specific to this Application script type. The Copy flag indicates 
whether or not the application will only be copied. The Use flag indicates 
which date to compare for the updates. Normally the creation date is used to 
compare applications. _ 
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Script Options 


hee: © Application @ Installer © General 


Group: |Hobbes Group 


Script Name: | System Installation 12.0 


C Allow User to Specify Destination 


22). The Installé 
mechanism, utilizing 


script's file name and a check box which optionally allows the administrator 
to let the user specify the destination location of the Installer's script (instead 
of the existing destination contained within the Installer script). 


The Installer script must be copied into the folder along with its associated 
files. 
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Script Options 


Script does 
Type: © Application Oinstaller © General 


Group: | Hobbes Group 


Use: © Application's Creation Date 
® Application's Last Modification Date 


ot falling intg 


available is\the Usa flag whi 


Networking Group 
ResEdit Users Group.. .- 


Bridge Development Group 


Figure 3-24 : Group Pop Up Menu 


The group pop up menu can be used by the administrator to provide a simple 
security mechanism for the script. The pop up menu (Figure 3-24) displays 
the list of available AppleShare groups. The administrator selects one of 
these groups to be used by this script. Normally the group selection will be 
the standard software distribution group (e.g. Hobbes Group), however it can 
be changed to any existing AppleShare group. Remember that only members 
of the selected group will have access to the script. 


Since folders can only have one group assigned to them, the administrator 

may get an alert (Figure 3-25) if he attempts to change a group when there is 
already a group assigned to that folder. This can happen if the script's folder 
has already been assigned a group by an earlier script. The administrator can 
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overrule the group assignment, however all script's groups linked to that 
folder will also be changed. : 


The script's folder has already been assigned to 
group “Networking Group". Are you sure you 


want to change it? 
[Cancel | 


Figure 3-25 : Group Change Alert 


Options 
Server Conn 
Delete Scrip 


Delete Script 


If the frontmost window is a script list window and a script has been selected, 
this menu command allows the administrator to delete the script and it's 
associated files. Files are only deleted if no other script is linked to the script's 
files. A confirmation dialog appears before the delete occurs providing an 
escape mechanism. 
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What is it? AppleTalk 2.0 Mac involves changes to the Macintosh AppleTalk drivers 
and utilities to implement AppleTalk 2.0 protocols. AppleTalk 2.0 protocols will permit 
more than 254 nodes to reside on the same AppleTalk network. In addition, in the 
presence of a router, such networks will be able to be divided into a number of different 
zones. AppleTalk 2.0 will also be more efficient in its use of broadcast traffic, and will 
attempt to eliminate the extra network hop currently involved when sending an internet 
packet. See "AppleTalk 2.0 Protocol Specification Proposal” for details. 


EtherTalk 2.0 Mac and TokenTalk 2.0 Mac are the two deliverables of the AppleTalk 2.0 
Mac effort. Each will be shipped on an Installer disk, much like the current EtherTalk 
1.0 Installer. 


AppleTalk 2.0 Mac and the overall AppleTalk development effort: AppleTalk 2.0 Mac is 
just one part of the overall EOD oe 2.6 eel ine most critical other piece is 
: mesh—A functioning version 


of this product i is necessary for the j ppleT¢ pceed into its more 
advanced phaseg, ang pteFalk drivers will be shared 
between North 2.) and fif is overed in “North 2.0 
ERS." Other related 008 (network 
management), Ag 

What does and dée anag in AppleTa dTalk 2.0 defines two types of 
networks, both ¢ aul ternet. Non-extended, or 


LocalTalk, EtherTa loon greater than this number. 
Non-routing nodes on non- seviended AppleTalk networks will not have to change at all. 
This includes all devices on LocalTalk, unless they're running a router. Non-routing 
nodes on extended AppleTalk networks will need to change, as will all routing nodes 
(even if only directly connected to non-extended networks). Thus any Mac wishing to 
use EtherTalk 2.0, TokenTalk 2.0 or North 2.0 will have to change. 


What will these changes involve? The most significant change will be replacement (o) 
the ROM-based MPP driver with a RAM-based one, which will be loaded out of a file 
named "AppleTalk" in the system folder. This is expected to use about 6K of RAM. The 
ATP driver should not have to change. Nodes upgrading from EtherTalk 1.0 will also 
have their LAP Manager and Network CDEV replaced. Additionally, the appropnate 
ADEV (alternate AppleTalk device) file will be needed (i.e. an "EtherTalk 2.0” or 
"TokenTalk 2.0” file in the system folder). 


Macintosh module details: The picture below illustrates the structure of the 


AppleTalk code in a Macintosh (either 1.0 or 2.0). The boxes in bold are part of 
AppleTalk 2.0 Mac. 
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North DA 


North code 
LAP Manager | 


EtherTalk 
ADEV 


Network CDEV | 
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| 
TokenTalk 
ADEV 


LocalTalk 
ADEV 


CDEV, which runs unde 


Details of each module are 


MPP: MPP has always been the core of the Macintosh implementation of AppleTalk. 
The Mac Plus, SE, and II all contain MPP in ROM. In these machines, MPP includes an 
implementation of the LocalTalk Link Access Protocol (LLAP — formerly ALAP). In the 
EtherTalk 1.0 product, a low-memory hook was used to replace LLAP with a call to a 
new piece of code called the LAP Manager. The LAP Manager was then responsible 
for calling the current ADEV. 


MPP also includes a dynamic-address assignment algorithm, DDP, NBP, the RTMP 
stub, and EP (the écho protocol). For AppleTalk 2.0 Mac, changes to MPP are too 
extensive to consider patching out part of MPP. For this reason, the ROM-based 
version will be replaced by one read out of the "AppleTalk" file. The "AppleTalk" file 
has been used by AppleShare and other products whenever it was found necessary to 
replace the AppleTalk drivers. 


Changes necessary to MPP include: a new address assignment algorithm (possibly 
including choosing a zone name if none is currently configured), changes to the DDP 
forwarding algorithm, changes to NBP to verify the zone name on incoming packets, 
addition of calls for obtaining new information, and the addition of a ZIP stub. Itis also 
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deemed desirable that the same version of MPP run on North, so some changes will be 
necessary to accomplish this. 


It is undecided at this point whether the new MPP will include an implementation of 
LLAP in it, or rely on a LocalTalk ADEV to perform this function. North will certainly 
require a LocalTalk ADEV, as it always has. 


MPP may need to include some user interface code. For instance, if MPP is opened on 
an extended network, and no zone name has previously been selected, MPP may wish 
to query the user at that time. Alternately, a zone name could be picked at random, and 
the user could be required to use the Network CDEV to select the zone (which he 
should have done at some point anyway to select the extended network in the first 
place). 


It may also be desirable for MPP to alert the user as to changes in the status of the 
internet. Specifically, under certain rare conditions, the user may need to restart MPP 
to be able to communicate on the internet after a router comes up. He could be notified 
of this event through the notification manager. 


The LAP Manager: ane LAP Manag 


eris essentially a an 1 extension of MPP to ade 


extended network. W 
clicking on its ico 
on that network. 
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Control Panel 
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Keyboard 
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NewHaven = 
PC Engineering 
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to the Ethernet 


ntogh is an enfirely new product. The rest of 
this document is devoted tdetailing the-dnctionality aad impldmentation of the 


TokenTalk ADEV and support utilities. 


The following figure diagrams two potential implementations of TokenTalk Mac. Inthe 
first one, the majority of the TokenTalk functionality is implemented on theTokenTalk 
smart card itself. The processor on the card removes some of the load from the main 
CPU, especially the processing of AARP (AppleTalk Address Resolution Protocol) 
packets. However this implementation would require third-party developers of Token 
Ring cards to re-implement this functionality for their cards. The second approach 
implements TokenTalk on the motherboard; third-parties would only have to provide a 
compatible Token Ring driver for their cards. 


The bold boxes indicate where most of the TokenTalk functionality is implemented. 
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: ; MR-DOS is the operating system running on the Token Ring 
smart card. It provides scheduling, timing and IPC (inter-process communication) 
services. Apple IPC is a Mac OS driver used to communicate between the 
motherboard and processes running under MR-DOS. 


TokenTalk process: Under scheme 1, when the TokenTalk ADEV on the motherboard 
is called by MPP to send/receive a packet, it calls Apple IPC to send a message toa 
peer process running on the Token Ring card. This process, the TokenTalk process, is 
responsible for most of the implementation of the TokenTalk Link Access Protocol. The 
two main aspects of this are AARP and the encapsulation of AppleTalk packets. 


802.2 LLC Interface and SNAP/source routing: The TokenTalk implementation makes 
use of two general purpose processes running on the card, both of which are also used 
by other services (e.g. 3270 emulation). The 802.2 LLC Interface process provides a 
standardized message-based interface to an implementation of 802.2. The 
SNAP/source routing process provides support for IBM source routing bridges and also 
SNAP (sub-network access protocol) demultiplexing. 


LLC Interface would remai 
necessary to the upper le 
(connectionless) service. 


installation process will install okenTalk ADEV, and the current versions of MPP, 
the LAP Manager and the Network CDEV. It will also install two files, currently called 
"TokenTalk Prep" and "Apple IPC", containing TokenTalk specific items such as the 
TokenTalk process and general purpose items such as the MR-DOS operating system 
and downloader and Apple IPC. 


Issues: A major issue revolves around the co-existence, on the same Token Ring 
board, of this product with other Token Ring products. The most immediate one is 3270 
over Token Ring. The current card only has 512K of memory. TokenTalk will take less 
than 100K, and 3270 seems to be able to fit in the remaining space. Issues of 
co-existence with MacAPPC and SMB also need to be addressed. 


External components: The Macintosh TokenTalk software is dependent ona number of 
components not being developed specifcally as part of the TokenTalk Mac effort. | 
These are listed below: 


(1) The TokenTalk/NB Token Ring card 

(2) The implementation of the 802.2 LLC from Ti (Type | only) 
(3) The 802.2 Interface (Type ! only) 

(4) The MR-DOS operating system and Apple IPC 
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The Serial IOP has been provided in Four Square primarily to offload the real 
time LocalTalk processing from the 68030. This allows the transmission and 
reception of packets without the need for the 68030 to disable interrupts for 
extended periods of time. This will also be a benefit for any other synchronous 
drivers which may be implemented on the builtin serial ports. 


There are two modes the Serial IOP can operate in, IOP and Bypass Modes. In 
IOP mode the Serial IOP has control of the SCC. In Bypass Mode the 68030 has 
control of the SCC. Bypass Mode provides a compatible operating mode for 
those drivers which are not supported by the IOP. A Serial Control Panel 
Device is used to control the Serial IOP's operating mode. The operating mode 
setting is stored in Parameter RAM. For the user the IOP Mode is designated the 
"Enhanced Communications" mode and the operating mode is controlled by 
either enabling or disabling the "Enhanced Communications" (or IOP) mode. 


The two SCC drivers currently supported on previous MACs, namely the Serial 
and LocalTalk alae. ported on the IOP. These drivers are able to 
operate in eithe pass Mode - etermine at open time 


IOP Mode its 
will be intercqpted 4 an alert\ will be posts ‘f ingicating that the current 
program require "Enhanced Communicatigfs" bg disabled on the Builtin 
Serial Ports. Po i 


The Builtin LocalTalk Driver is imbedded in the MPP driver and _ supports 
AppleTalk communications on the Printer Port. LocalTalk is one type of 
AppleTalk LAP, Link Access Protocol, which is supported by AppleTalk, with 
EtherTalk being an example of another AppleTalk LAP. ~ Normally, the 
application does not access the LAP layer directly but only indirectly through 
the use of higer layer protocols such as ATP, AFP and ADSP. However LAP 
services can also be accessed directly in order to send and receive packets 
directly on the cable. 


The LocalTalk Driver on Four Square is able to run in either IOP or Bypass 
Mode as mentioned above. In either mode the Four Square LocalTalk LAP 
Driver will provide compatible LAP Services and compatible LAP Protocol 
Handling as that provided in non-IOP MACs. Consult Inside Macintosh Volume 
II Chapter 10 for details on LAP services. Consult Inside AppleTalk for a 
description of the LocalTalk protocol. 
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Serial _Dri 


The MAC's Serial Driver provides basic Asynchronous Communications 
Services. The primary clients of the Serial Driver are Terminal Emulators, 
Serial Printer Drivers and Telecommunications Programs such as AppleLink. 
The Serial Driver supports communications on both the Modem and Printer 
Ports with two drivers provided for each port, an input and an output driver. 


The Serial Driver provided on Four Square will be able to operate in either IOP 
or Bypass Mode as described above. In either mode the Four Square Serial 
Driver will provide compatible services as those provided by non-IOP Serial 
Drivers in previous MACs. Consult Inside Macintosh Volume II Chapter 9 for 
the specification of the standard Macintosh Serial Driver. 


Serial Control Panel Devi 


The Serial Control Panel Device is shown in ee 1. It Penney allows the 
user to change betweqn—lOR—an pe OR—everates3n IOP Mode 
when Enhanced Comm Bypass Mode 
when Enhanced Communications is Digabled. 


Serial Control Panel 
Figure 1 
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Both ports must be inactive before the user is allowed to change the mode. 


Serial IOP ERS 


If 


the user attempts to change the mode while a port is being used an alert will be 
shown in figure 2. 


posted as 


1/11/89 


You cannot change the Mode of 
[ \ Communications while a Port is 
active. Quit any current Serial 
Applications and try again. 


Figure 2 
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Executive Summary 


Plan Road Map 

This plan for Blue System Software is divided into three parts: 

= Section | Plan Overview: Overview of direction, priority features, and summaries of new features 

a Section II Details of Implementation: Tactics, user and developer impact, one-megabyte support, and competitive 
position 

= Section Ill Detailed Feature Discussion: Descriptions of each software project under development and investigation 

For an overview of FY89 Development, read the entire Executive Summary and Section I. 


Release Scheduling 

The Fiscal Year 1989 development plan is designed to maximize effort toward the delivery of a major feature release in 
October. Three interim releases will also be delivered in FY89 to support new CPU products and to support 32-Bit 
QuickDraw/Color PostScript printing. However, virtually all of the feature extensions will be delivered in the October 
release, codenamed Big Bang. Users benefit by our grouping features into one big release in that the majority of users 
will have to upgrade their software only once next year. To the extent that we minimize the interrelationships of Big 
Bang features, we can reduce the development risk. __.<""""? 


Focus Areas 
Macintosh system software cover: 


The three priorities for operating systems development in FY89 are 32-Bit Addtessing interProcess Communications 
(IPC), and Virtual Memory. 32-Bit. Addressing will allow our 68)20/030 machifies to acgommodate more than 8 
megabytes of address space, which will support larger applications and more concurtently active applications. IPC will 


3 ey 


provide the means for applications to send messages to ong another and;to leverage off each other's functionality. IPC 
will also act as an enabling technotegy for user scripting-and will allow developers fo write more modular applications. 
Virtual memory will allow users of 680207030"machines to use more concifféiitly active applications by ieating the hard 


disk as an extension of physical RAM. 


Imaging 

In the spring, we will ship 32-bit QuickDraw as a user installable extensions to System 6.0.3. This will extend Apple’s lead 
in color functionality and provide for photo-quality color on high-end systems. With Big Bang, Apple will also deliver an 
open-format outline font system and the “Layout” manager. Outline fonts will give users more flexibility in dealing 
with font sizes and styles. The layout manager will give developers a standard way to attractively lay out text on a line. 
The highest priority extensions beyond these are those that cannot reasonably be added by developers on an 
application-by-application basis. 


Desktop Services 

Desktop services covers all standard programmer and user tools like the Finder, User Interface Toolbox, and other user 
and application utilities. With Big Bang we want to simplify system setup and system management functions as well 
as to provide new tools to give applications additional power. New Finder is our highest priority in Desktop Services. 
New Finder will unify most system functions into one consistent interface and will provide both more power in dealing 
with large volumes of files and the hooks for Finder expansion. Other important 1989 Desktop Services projects include a 
new Installer program (easier system setup), the Language Manager (standard text-processing services like spell- 
checking and thesaurus for applications), an API for access to remote SQL databases, user interface extensions, and 
InterApplication Communications (“hotlinks” for applications). 
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System Integration 

Several System Integration efforts are underway for 1989. These include the new Print Architecture (codenamed Ginsu), 
which will allow Macintosh to support a greater range of output devices and will provide improved device control, and 
the File System Manager in combination with the DOS File System, which will provide Macintosh desktop access to MS- 
DOS disks with Superdrive. The other System Integration feature will be a Color PostScript driver scheduled for release 
in the Spring of 1989. 


Transition to 7.0/One Megabyte Systems 

The new features of System 7.0 will cause Macintosh memory requirements to grow by 100-300K. To run adequately, 
Apple will recommend that System 7.0 be installed on machines with at least 2 Megabytes of RAM. To allow user and 
developers to make appropriate plans, the transition to System 7.0 will be spaced out over 6 to 9 months. During this 
period, System 7.0 will be shipped with higher end configurations of Macintoshes, while System 6.0 will be shipped with 
one megabyte entry configurations. 


Competitive Position 


The 1989 software plan will strengthen Apple’s competitive position. While certain areas of our system will lag 
competitive functionality (operating system services is the most notable example), our overall system will continue to 
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Project Description ios 

IPC InterPrdcess ‘Comifitiinications. for applications eg 

32-Bit Addressing 68020/030 class machines to address up to 4 gigabytes (gurrent limit is 8 megs) 
Virtual Memory 68020/030 class machinés can use their hard disks as a-€xtensign to physical RAM 
32-Bit QuickDraw Photo quality color; up to'16 million tolors per pixel” , 

Color PostScript Driver Color Postscript printing capability ’ rs £ 

Outline Fonts Mathematical font description provides increased flexibility and quality (Bass) 
Layout Manager Improves readability’of text across devices and charactes sets 

New Finder Unification of-system.utilitiés into consistent interface;-improved file management, extendible 
Installer 3.0 Simplified software installation and update 

Database support Standard application access to remote SQL and non-SQL database services 
Language Manager Standard application text services for spell checking, thesaurus, etc. 

IAC InterApplication Communications; dynamic update of data between documents 
Script Manager Enhanced Script Manager with International Control Panel and Key Caps 


Multiple Script System Support for concurrent, multiple Roman and Non-Roman character sets 
Menu/Window Extensions Tear-off menus and floating windows 

New Print Architecture Allows for easier development of output drivers and extended device control (Ginsu) 
File System Manager Foreign file system integration with Macintosh desktop 
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Mission and Goals | 

Our system software mission is to create platforms which inspire and support the development of the best personal 
computer applications. Macintosh should always be characterized by providing an intuitive user interface, powerful 
tools and seamless integration of applications, hardware and data. The combination results in a superior user experience. 
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still considered the best available, they are no longer the best possible. 


Our goal is to develop system software, capabilities that take full advantage. of.our hardware and provide software 
that challenges applications to grow. We will add breadth to our software that will result in new capabilities for 
developers to take advantage of. We will also increase the depth of our software to provide more capabilities 
transparently to current applications. The net effect will be to provide more power to users. 


We already have extensive lists of the capabilities that our developers seek. We also have great ideas that will enable 
applications to do more than they thought possible. However, since we cannot deliver everything at once, we must 
decide how to best spend our valuable software development resources. The purpose of this plan is to explain our 
priorities and focus for FY89. The plan also briefly discusses blue system software development priorities beyond FY89. 
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Where We Are Headed 

The major functional areas of development are Operating Systems, Imaging, Desktop Services (including Finder, 
Menu/Window routines, and other toolbox services), and System Integration (the code that unites applications, 
hardware, and data with each other and with the system in a natural and seamless way). 


The chart below summarizes the 1989 development priorities and known development projects for 1990 and beyond. 
The projects chosen for 1989 development are those projects that are most important in terms of overall developer/user 
impact, ability to extend our competitive advantages and our ability to deliver with Big Bang. Discussion about each 
functional area follows the summary chart. (Note: This chart only covers the major efforts; other projects are also 
discussed in following sections). : 


Bluc System Software Priorities 


Functional Area 1989 Development Priorities 1990 Development Priorities 


IPC 


Operating Systems Protection 


une QnBit- Addressing of unudetwork Booting 
Virtual Memory Pre-Emptive Scheduling 


L3ZBitQuickDraw “~’ 
Outline Fonts *, 
Layout, Manager’ 


_”’ Impfoved Drawing Engine 
"Hardware Acceleration 
# File Formats 


Desktop Services New Finder i i Integrated Electronic Mail 
oy Trstaller 3.0." User Scripting 
“~~Tyatabase API Help 
Language Manager Navigation tools 
IAC 
Script Manager 
Multi-Script System 


Menu/Window Extensions 


System Integration Color PostScript Driver Imaging Device Manager 
CPU ROMs Data Format Standards 
Video ROMs WYSIWYG Color 
New Print Architecture DOS File System 


File System Manager 
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Operating System 


Key 89 Goal 1989 Development Priorities 1990 Development Priorities 


« Increase available PC Protection 
application address 32-Bit Addressing Network Booting 
Virtual Memory Pre-Emptive Scheduling 


space and provide 
application to appl- 
ication communications. 


Operating system services of the Macintosh are probably the weakest of the four functional areas. MultiFinder is a great 
step forward, but we must push further. With MultiFinder, users can quickly switch among several RAM-resident 
applications and have several background tasks running concurrently. Examples of background services available today 
include printing, spreadsheet recalculation, remote file transfer, and others. 

However, many highly desirable features that are standafds of OS/2 and UNIX are still missing; In FY89 the key 
goals for operating systems development are. to. provide.forian enlarged addressing.capability and-interProcess 
Communications. be sah a , ae 


1989 Development Priorities 


Enlarged Address Space/32-Bit Addressing* ; ; 

On today’s Macintosh II and all 68030. Macinidsh machings;‘the total amoyht of memory that can be accessed is 8 
megabytes, no matter how much memory’is-installed’ifi the machine. Comipanies-are’ already selling 4 MB SIMMs 
(allowing up to 32 MB for a Mac II), but the Mac OS only allows use of 8 megabytes. While this limitation is now 
apparent to only a few users (image processing, artificial intelligence, engineering design applications, and such), within a 
year this memory limit will become a common concern for many mainstream users—particularly those who want to 
use a set of the latest productivity and publishing applications under MultiFinder. Also, to successfully stand up to Sun 
and NeXT workstations, our new, high-end Macintoshes—Aurora and 4-Square—must be able to address more than 8 
megabytes. The 32-Bit Addressing project provides the solution by giving 68020/030 Macintosh machines the capability 
to address up to 4 gigabytes of address space, including up to 128 megabytes of RAM. The 32-Bit Addressing project is 
also a necessary prerequisite to developing virtual memory to support large applications. 


InterProcess Communications 

InterProcess Communications (IPC) is a low-level, developer-oriented mechanism that allows one application to send 
data to another application. The need for IPC is critical. MultiFinder allows many applications to coexist in one machine, 
but it does not provide any means for those applications to talk to one another. IPC delivers on the promise of 
MultiFinder by allowing applications to leverage off the special services of other applications. With IPC, huge monolithic 
applications such as FullWrite can give way to smaller, more specialized functional modules (for example, a word 
processor that uses a separate telecommunications process). Developers recognize this need; IPC is the most frequently 
requested feature. IPC also paves the way for future Apple development. By building on IPC, applications can send 
commands to one another; this feature is the enabling technology for system-wide user scripting. (Note: 
InterApplication Communication, a desktop services project described later on, is a user tool for connecting documents 
in a persistent way.) 
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Virtual memory 

With virtual memory, the operating system can run more applications and larger applications by moving inactive 
portions to the hard disk in a manner transparent to applications. To users, virtual memory provides a software solution 
to the RAM shortage. To developers, the lack of a virtual memory capability has been a common concern for some time. 
Without an Apple solution, these developers have been forced to develop their own virtual memory mechanisms. 


Other 1989 Development Efforts 


Beyond the key development projects lie numerous other areas for improvement. Included in this tier of projects are 
Input/Output Enhancements and File System Enhancements. 


Input/Output Enhancements 

Improving the I/O subsystem is a large FY89 effort. A rewritten SCSI Manager will provide a more general SCSI system 
interface and will offer asynchronous operation and greater reliability. In addition, future Macintosh hardware (4 
Square/F19) will permit offloading of certain CPU-intensive activities to specialized processors. Among these activities 
are disk I/O (SCSI DMA), AppleTalk processing, and keyboard and mouse processing. Adapting the operating system to 
take maximum advantage of these new capabilities will be a challenge in FY89. 


File System Enhancements | i ; ; 

Several modifications to the file system, are. planned, primarily to sipport.other-operating.systemy'and desktop service 
projects. With a new File Link methanism, applications will be able to,focate documents even’after a folder move. A fast 
catalog search primitive will permit the ‘Finder and othef applications to quickly search a hafd disk for files matching 
specific criteria. Finally, a finely-tuned B-tree" package will be‘available for application use;* 


1990 Development Priorities 


*e, 
, 


We should structure the Macintosh, operating’ system to,pfomote system reliability:through protected address space 
operation. In higher level terms, the system-can-buitd “walls” around applications by running each application in its own 
address space. Then, an application that runs amok cannot corrupt other running applications, user data, and system 
data structures—a problem that can occur today. 


We should realize the “diskless Macintosh” by implementing network booting—the ability to start a Macintosh 
from a network device. Certain markets, such as K-12 education, require network booting to make classroom networks 
manageable. Network booting is thus an essential component for our low-end product line. It is important to note that 
the while the hooks for network booting may be implemented in a CPU ROM, there is no current 1989 effort to develop 
a system level network booting feature. Network booting ranks lower in priority than other mainstream OS projects 
because of its technical difficulty and its more limited audience. 


Further out, the operating system should provide preemptive CPU scheduling. While MultiFinder already implements 
a cooperative CPU-sharing scheme that meets many needs, everyone can benefit from a finely tuned, more regular 
preemptive scheduling capability. Users will notice that applications run more smoothly and more responsively (for 
instance, without stutter during background printing) and will also find that more applications can accomplish work 
while running in the background. For developers, preemption releases them from the burden of proactively cooperating 
to ensure system responsiveness—applications able to run in the background become easier to write. Preemption will 
probably not be available until Pink. 
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Imaging 


Key 89 Goals 1989 Development Priorities 1990 Development Priorities 


» Significantly increase 32-Bit QuickDraw Improved Drawing Engine 
the numberof Outline Fonts Hardware Acceleration 
drawing and graphics 
manipulation commands Layout Manager File Formats 
available to developers. | 


* Improve imaging 
integration with input 
and output devices. 


Over the last two years, Apple’s imaging system features’ fidve fallen behind the demand of customers and developers 
encountering increasingly sophisticated applications and markets. In’ terms of basic textbook drawing engine features, 


SeeesecercerecreweeeePrerereree seers 


wy ae 


1989 Development Priorities 


Improved Color: 32-Bit QuickDraw 

Our highest priority in FY89 is to ship 32-Bit QuickDraw, extending the color capabilities of the Macintosh from 8 bits, or 
256 colors, to 32 bits, or 16 million colors. Apple is already late on this capability; we publicly committed that we would 
deliver this functionality in the fall of '88. This product will attract new developers and encourage new applications for 
the Macintosh in markets not currently supported. As part of the 32-Bit QuickDraw project, we would like to improve 
QuickDraw’s accessibility to standard graphics coprocessors; this would allow customers of such devices a potential for 
2 to 3 times original speed on some routines. 


Improved Text: Outline Fonts, Line Layout Manager 

We are also developing an outline font capability, compatible with Pink, that will give users access to more font sizes 
and styles and will make fonts on QuickDraw printing devices (ImageWriters, Fax Modem, LaserWriter JISC) have a 
higher-quality appearance. Many developers are currently trying to implement application-specific versions of this 
technology and will benefit from a single standard. Simultaneously, we are developing a centralized, device-independent 
mechanism for line layout that will improve the readability of text across devices and international markets. These two 
projects will help reestablish the Macintosh on the forefront of text handling. 
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1990 Development Priorities 


Strategy to Evolve to a Fully-Featured 2D Graphics Engine 

The highest priority for development beyond 1989 is to extend the 2D graphics functionality with features that cannot 

be reasonably added by developers on an application-by-application basis. These are features that Apple must provide 

for them to become pervasive features of the Macintosh. These key features are: 

a Varied DPI Bitmap Handling—allowing varied resolution images to display at the appropriate size. This is particularly 
important with scanner technology and in image visualization markets. 

we World vs. Device Coordinates—allowing mathematical mapping of an offscreen coordinate space to the device space. 
This enables applications to be “device independent.” 

w= Fixed and/or Floating Point Coordinates required for precision graphics common to the workstation world. 

ws True Hardware Acceleration—hardware acceleration allows graphics commands to be off-loaded to another processor. 


Lower priority feature extensions include those features that developers can and have already implemented 
themselves, but could become pervasive if Apple supported them in the basic graphics engine: 
= Rotation and Skewing of Text—allowing mathematical manipulation of our outline fonts. 
@ Full Transformations of Objects—allowing mathematical manipulation, including skewing, of any object. 


This functionality is crucial to the longevity of Macintosh. Appl has already lost many leadirig edge applications 
developers to their own graphics models.in.search.of greater features and.performance..Howeyet, modifying portions 
of QuickDraw to support this type of functionality would be technically difficult Cif net impossible in some areas) and 
would require developers to re-imiplerriefit their applications with changed interfaces. Our implementation choices are to 
either implement a new drawing éngine ort teasonably extend QuickDraw or to" pursue’ both. 


Implementation with New Drawing Engine 


An effort to implement a new drawing erigine is alfeady underway under the code name of Skia. In addition to 


providing all of the above features, Skia woyld.also provides” : ; 
| resolution regardless of device 


om 


Hairlines—a draw line command-that draws at one, pix 
Curves—a consistent spline-like primitive" 
Error Checking—a mechanism that flags the application if the graphics routines fail 
Path—connected line segments and curves, along which text objects can be placed 

Improved Hit Testing—a mechanism to detect which object the cursor is on 
Editable/Parseable Pictures—a file format that allows the application access to specific objects 
Specialized Typesetting—a way of connecting lines through end caps and line joins 


e 


Taken together, the above features would provide an extremely compelling graphics environment. Open issues for 
this project exist in the implementation of the interfaces, its integration with the rest of the Blue system including 
Printing, and the delivery mechanism if it fails to make the Big Bang schedule. 


Implementation with QuickDraw 

While it is impractical to get all of the new graphics functions that we want within the current QuickDraw model, there 
are substantial advances that could be made. These additions to QuickDraw are practical and would provide the greatest 
positive impact to developers and customers: 


w Performance Improvements, including Hardware Acceleration (see below). 

w= Varied DPI Bitmap Handling 

w Rotation of Text 

w Full Transformations of All Objects 

a Editable /Parseable Pictures 
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We are currently pursuing some of both implementation paths. Actual 1990 deliverables are to be determined and will be 
heavily impacted by resource constraints. 


Improved Performance 

The weaknesses of our graphics programming model are made even more glaring by its performance for specialized 
applications and markets. As part of the 32-Bit QuickDraw project, we would like to improve QuickDraw’s accessibility 
to standard graphics coprocessors; this would allow customers of such devices a potential for 2 to 3 times original speed 
on some operations. Another relatively small project involves making some minor additions to QuickDraw that would 
flag an additional coprocessor, such as that on the SEG card, on an application's programming techniques. In addition, as 
hardware for block transfer modes may become a reality, the graphics model must take advantage of such relatively 
application-transparent performance improvement. Finally, it is possible that software improvements could be made to 
the performance of the basic “move to’-“line to” sequence. 


Color Integration 

Apple must maintain its edge in manipulation of shared color between applications, the system, and the customer. 
Potential projects in this area include improvements, extensions and enhancements to the Color Picker and the Palette 
Manager. A simple change would be to implement a “real life” transfer mode to support CYM color combinations as 
most people learn them: red + yellow makes orange, blue + yellow makes green, red + blue makes purple. This would 


Other Opportunities i ; s 
Font Manager—the code everyone loves‘te-hate. é f : 
GraphEdit—the “TextEdit” of graphies.objects for.buitding graphics applications. : 
Alpha Channel support—using the last eight bits of 32-Bit QuickDraw for transparency. 

Error checking in QuickDraw—a mechanism that flags the application if graphics routines fail. 


Animation—low level tools to support applications’ animation systems. 
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Desktop Services 


Key 89 Goals 1989 Development Priorities 1990 Development Priorities 


* Improve the User's New Finder Integrated Electronic Mail 
. i Pe a with Installer 3.0 User Scripting 
Database API Help 


« Standard Access to Language Manager Navigation tools 
Common Resources ia : i 


Script Mana 
* Create New, Enabling ee Scr oe 
Technologies ulti-Script System 
Menu/Window Extensions 


and Functionality 


ceigiee ea Gs Rs ae Dot 


for more simplicity. 


AMON 
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1989 Development Priorities 


m@ Improve the User’s Experience with Macintosh 

The Macintosh, famed for its ease of use, is still a difficult machine to use. More specifically, our users are befuddled by 
system software that is hard to install; by inconsistencies in concepts (for example, dragging a disk to the trash to eject 
the disk); and by the lack of tools to organize and to navigate through information in desired ways. 

The user’s first hour with the Macintosh must reinforce his or her decision to buy; the single most important result of 
that first hour is a user's sense of control, mastery, and possibility. We can simplify the user interface and extend its 
power through greater intuitiveness; increased interface consistency among System Utilities; more features for the 
organization, search, and retrieval of data; more intelligent operation; and an integrated help capability. 


New Finder 

New Finder is the most important and largest desktop services project for the year. New Finder will bring together 
various system services utilities, such as Font/DA Mover, Control Panel and so forth, under one consistent user 
interface. In addition, New Finder will add new features that help the user better organize, search for, and retrieve files 
and folders both locally and over a network. New Finder will be extendible so that both Apple and third-party 
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applications that provide desktop services, such as electronic mail, can use the Finder interface. A standard on-line help 
capability will aid the user's introduction to the Finder. 


Installer 3.0 

~ Installer 3.0 will make installation and updating of system software easier for users. This ease will come from a more 
intuitive user interface and more intelligent operation. For less experienced users, Installer 3.0 will automatically instal! 
the right system resources by detecting what configuration of hardware is present. More experienced users will be able 
to customize their installations. 


ws Standard Access to Common Resources and Functionality 

The Macintosh should provide standard access to common resources and common functionality such as databases and 
text services. When the Macintosh embeds common functionality in system software, application developers can forge 
ahead and concentrate on implementing innovative new features. Users benefit from this arrangement by having a 
single, consistent interface to these resources oF services. The perfect example is the StandardFile, which provides one- 
stop shopping for opening and saving files. 


Database API . 

The Database API project will provide applications with standard toolbox-level access to remote database hosts. A 
single, consistent user interface for agcessing databases and pervasive database-capability-in-many-applications are the 
chief user benefits. H i ; 


: ? 
2 . 
ee D 


Language Manager , 


With Language Manager, applications will have. access to stafidard text services such a6 spell-checking, dictionary look- 


up, and thesaurus. Users will benefit because more ‘applications'will support text sefvices, ahd all applications will have a 
richer set of text services. Users can use one interface ‘and one dictionary across Fiany applications. Developers will 


benefit by having a standard way 6 add additional text processing modules. # 


The Script Manager project enhances fiinetionality.of-the script manager ind.related software associated with 
supporting intemational writing systems and localization issues. 


Multiple Script System 
Multiple Script System will allow applications to concurrently support Roman and non-Roman writing systems, such as 
kanji, Arabic, and Croatian. 


w Create Enabling Technologies 
By laying the fundamental groundwork, the toolbox should entice developers to create powerful new applications that 
build on the foundation of desktop services. The toolbox should act as a bridge, not a barrier. 


InterApplication Communication 

InterApplication communication (“IAC") brings data sharing to Macintosh applications. With IAC and IAC-aware 
applications, users can create “hot links” between application documents so that designated data in one is updated 
automatically in another, eliminating repetitive cut-copy-paste routines, IAC could also be used to link several users to 
the same data on an AppleShare server. 


‘Menu/Window Extensions 
Also under development are several user interface extensions that provide tear-off menus for all applications and better 
handling of application windows. 
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1990 Development Priorities 
Beyond FY89, we want to implement integrated electronic mail, more comprehensive user scripting, standard on-line 


help for all applications, and 


| A 


better tools for navigating through information. 
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System Integration 


Key 89 Goal 1989 Development Priorities | 1990 Development Priorities 


° Improve integration with Color PostScript Driver Imaging Device Manager 
shipping products and CPU ROMs Data Format Standards 
ats hardware Video ROMs WYSIWYG Color 
: New Print Architecture DOS File System 


File System Manager 


System integration is one of the unique ways Apple provides value to the Macintosh user while taking advantage of its 
unique industry position in owning both the hardware and the system software. Through the establishment of 


such as the boot process and diagnostics for manufacturing. Finally, by placing.as much of system software into ROM 


software features. 


re a a se 


1989 Development Priorities 


Color Postscript LaserWriter Driver 

In F¥89, we will ship a Color PostScript LaserWriter Driver that will allow color applications to produce color output on 

color PostScript printers; an Apple-endorsed standard mechanism for color output has been notably lacking since the 

introduction of the Macintosh II in 1987 and has hurt our credibility in the Publishing, Presentations, and Scientific and 
- Engineering markets. 


CPU ROMs 

The ROM priorities are based on CPU Engineering priorities. Shipping products, which have highest priority and for 
which ROMs are expected to be built, are Esprit and Aurora. In addition, prototype ROMs for F-19 will need to be built in 
this timeframe. ROM development also includes implementing system software features. The two key system 
software features falling in this category are 32-Bit Addressing and network booting. As previously mentioned, 32-Bit 
Addressing is an essential part of the Aurora ROM so that the Aurora can handle more than 8 megabytes of memory. 
Network booting, as has already been highlighted, is considered important for the education market. 
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Video ROMs 
Video ROMs and the Slot Manager architecture play a key role in our ability to integrate our graphics software with our 
CPUs’ displays, in addition to our ability to turn out NuBus cards and, in FY89, new CPUs. The driver for each card is 
placed in the Video ROM and is critical for various functions of the system during boot time. We are working on 
redesigning our video ROM and Slot Manager architecture to support new configurations. Key projects that will be 
handled are: 

Cost reduced, shipping NuBus video card 

Cost reduced, large grayscale, NuBus card 

Small black and white NuBus card 

Large black and white NuBus card 

Prototype cards for new slots 


With the advent of on-board video, we will also be doing video ROMs for Esprit and Cobra II. 


New Print Architecture 

The difficulties of developing a Chooser-selectable output (printer) driver for the Macintosh are well known. Because | 
the mechanism for development has not been published, third parties have been unable to write drivers except by 
disassembling Apple's, and Apple-developed-drivers-tiave always been-time-consuming-endeavors. The New Print 
Architecture (codenamed Ginsu) will make development 6f output'drivers much easier and will result in Macintosh 
being able to support an enlarged range-of-output devices. Ginsu will also-make-it-easier-to control the devices in a 
standard way. Apple will selectively li¢ense.the.Ginsy toolbox interface to third-panty.developers who have products 
that complement our output device faitiily (such as film'recorders and plotters). The Ginsu project is expected to break 


all shipping third party printer drivers. .«"", 


File System Manager gree i } Fs Z 
The File System Manager (FSM) project will allow:for foreign file structurgs (such as MS-DOS, Apple II, UNIX, SMB, 
NFS) to be viewed and manipulated on the Macintosh desktop like any Macintosh file. With FSM, we will enhance the 


user’s ability to deal with data in tnultj-vendor environtnents. 
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1990 Development Priorities 


Imaging Device Manager | 

A graphics system with superior output is only as good as its display system and input capabilities. The imaging device 
manager project will provide a standard way for developers to access scanners, frame grabbers, and video overlay cards 
in a natural and seamless way. This will do for input devices what Ginsu does for printing and other output devices. It 
is also expected to allow third parties to provide image analysis packages , such as character recognition, in a seamless 
way to all applications. Use of these technologies will become pervasive as a result of this effort. 


WYSIWYG Color 

Another project we expect to begin work on in 1989 is that of picking a universal color model that will allow accurate 
communication of color information between devices of different color models and ranges. Throughout the world 
today, no personal computer or workstation company has been able to tackle the problem of ensuring that the color 
scanned in is the same as that which is displayed on the screen or is printed. The first step in this effort is to define a 
standard; the second is to implement routines that handle these color translations for the applications and device 
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The DOS file system is a File System Manager. extension for Supporting MS-DOS disks. on the Macintosh. With FSM and 
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the DOS file system, DOS volumes (accessed through Superdrive) will appear on the Maciritosh desktop just like 
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Where We Will Be 


With the delivery of Big Bang, we will have delivered a major step forward in the evolution of Macintosh system 
software. We will reap these important benefits: 


Macintosh will have the ability to support larger, more complex applications. (32-Bit Addressing) 

We will see applications beginning to work cooperatively. (IPC, IAC) 

We will have the best color support in our product class. (32-Bit QuickDraw, Color PostScript Driver) 

Users will have much greater flexibility in dealing with font sizes and styles. (Outline Fonts) 

Macintosh will be easier to set up and use. (New Finder, Installer 3.0) 

Spell-checking and other text services will be a pervasive Macintosh application feature. (Language Manager) 
Many applications will support dynamic data insertions or “hot links.” (IAC) 

Applications will begin to make use of remote SQL databases. 

There will be a greater range of output device choices for Macintosh. (New Print Architecture) 
Non-Macintosh file systems will be better integrated with Macintosh than on their native machines. (File System 
Manager) 

Users will have new capability in using and managing menus and widnows. (Menu/Window Extensions) 


oo 


With this set of expanded features, we will have major product introduction opportunity. 
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Plan Overview 


i 


Timeline 


The development time line is very aggressive. It is important to recognize that there are always two disks in 
development concurrently. While ordinarily this would be impossible to manage, the fact that 6.0.3 and 6.0.4 are 
hardware-only releases minimizes the number of development engineers that need to be involved with them. Most 
software engineers can continue to work on Big Bang. Also notice that the Alpha release of Big Bang is timed to 


slightly precede the May Developer Conference where we hope to disclose the entire Big Bang plan to developers and 
provide them with development code. 


Calendar 


Software 


ROMs 


Hardware 
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System Disk Release Strategy 

The FY89 plan is designed to meet three major objectives: 

= Deliver meaningful new functionality as soon as possible. 

= Accommodate needs of new and existing CPU and peripheral products. 
= Minimizing the update burden for the customer. 


‘The new system disk release strategy departs from a policy of twice-yearly releases to one of feature-driven major 

releases, with interim minor releases solely to support new hardware. With the 6.0/6.0.2 experience behind us, we changed 

the twice-yearly policy due to the following observations: 

= The installed base and developers accept the transition burden of one software release to another only when the 
increased functional benefit is apparent. For example, the transition to System 5.0 was far more traumatic than the 
transition to 6.0, but because System 5.0 gave users MultiFinder, there was a far greater willingness to deal with the 
bumps in the road. Major new features provide sufficient rewards to compensate for the pain of an upgrade. 

ws We have recognized that the amount of software that we want to do far exceeds our resource capabilities. Since we 
cannot do all that we would like, we must plan our resources so that the greatest portion of our time is dedicated to 
new features. System releases with anything but minor changes require tremendous engineering and testing 
resources. By lumping major functional changes into.one release, we use our engineering and testing resources more 


aerare'e'e: 


efficiently. i 


This strategy will focus all woik onthe October ’89 Telease and minimize all efforts that do-fiot directly contribute 
to that release. CPUs and networking products require, interim releases; however, through cdoperation with the other 
groups, we have minimized the amount of work required support the new products. However, it is critical that 
hardware and networking projects make“accominodations to, software priorities"This intludes minimizing the number 


of new ROMs and interim System disks. Without these accommodations, new Software Features will slip. 


By focusing on one feature-tich release only, thie installed’base will noyneed to update to interim releases, such as to 
6.0.3 or 6.0.4, because these releases support-only new CPL products. (The update product and shipping CPUs will always 
contain the latest version of the system.) Developers.will also be generally unaffected by 6.0.3 and 6.0.4. Thus, most 
customers can remain with the 6.0.2 release currently being shipped. Specific guidelines for who should update are 
contained in the individual descriptions accompanying each release. 
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Overview of Each Release 


Release 6.0.3 - RELEASED - 


Release 6.0.3 is a maintenance release that provides support for the Macintosh SE/30 and an update to Apple File 
Exchange. Although 6.0.3 will be shipped with all new Macintosh CPUs, the installed base will generally have no need to 
upgrade to 6.0.3. Networks of systems with a mix of 6.0.2 and 6.0.3 will work fine. System 6.0.3 will be released at 
January MacWorld. 


Interim Releases: 32-Bit QuickDraw and Color PostScript Driver (in Beta) 

32-Bit QuickDraw, which will be a patch file that a user drags into the 6.0.3 System Folder, and its accompanying 
Monitors CDEV and General File will be released for licensing to developers interested in shipping them with their 
products. It will be made available to dealers, to licensed bulletin boards and through user groups to the widest number 
of end users that would like to have it. The 32-Bit QuickDraw file, when installed, will appear as a color icon in the 
System Folder; otherwise, it will be.a. standard black-and-white icon. 
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The Color PostScript LaserWriter Driver will be licensed to developers of color PostScript ouput devices. 


o 
2 


This interim software will ship in the-spritig Product plans for-32-Bit QuickDraw ‘and tHe Color PostScript 
Laser Writer Driver are available from the Product Managers for the products.” é 


Release 6.0.4 (in alpha)” 


z 


Release 6.0.4 currently assumes that Esprit and.Aurora will-be supported’by this one system disk. 


A new version of Macintosh systétrSohware is tequired to support Esprit-and Aurora. The changes are necessary to 
support the new ROMS, in the form of ROM patches, and new hardware features such as Esprit’s Sleep and battery 
features as well as Aurora’s on-board video. 


Like System Software 6.0.3, 6.0.4 will provide no additional benefits to the installed base of Macintosh customers and 
Apple will not recommend that users in the installed base upgrade to 6.0.4. 


Release 6.0.4 will be included in all Macintosh CPUs as of the announce date of Esprit and Aurora. 


Overview of changes: 

Esprit ROM patches 

Aurora ROM patches 

A change to the Finder to support Esprit’s Sleep feature 

Esprit’s Control Panel Devices 

Esprit's Desk Accessory to control battery usage 

An updated Monitors Control Panel Device for Aurora 

A new version of HDSC Setup to support Esprit's Asynchronous SCSI Manager 
Installer 3.0 (multidisk installer) 


Acomplete product plan is under development for 6.0.4. 
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Big Bang 

Big Bang is a major system software release and will include support for the Spin CPU (minus remote booting). It will 

include numerous new features for new CPUs and the installed base. There will be a major push to move the installed 

base up to Big Bang. While all the features of Big Bang will probably not fit in one megabyte, there will continue to be 

one-megabyte system support (see One-Megabyte Support section). The new features in Big Bang include: 
InterProcess Communications (IPC) 
32-Bit Addressing 
Virtual memory 
32-Bi QuickDraw 
Outline Fonts 
Layout Manager 
New Finder 
Installer 3.0 
Database API 
Language Manager 
InterApplication Communications (IAC) 
Script Manager 
Multiple Script System 
Menu/Window Extensions — 
Color PostScript LaserWriter Driver 
New Print Architecture i 
File System Manager 
File System Enhancements Ss 
Music Sequencer ar a 
Audio Compression/Expansion 


PERSE SE PORN ET ETM TIO NTI SRE AEE EIEN? 
{eteeeweecererweeeesewerecereeeeTeeee Ns 


We expect to ship Big Bang id Octobe of 1989. However, all exterdal discldsures of Big Bang will state a 
calendar QI delivery date. cs Se & : i 
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Project Status 

The projects scheduled for the Big Bang disk have different levels of risk that have an impact on the overall schedule of 
the system disk. The following chart summarizes the risks of the projects based on staffing and technical difficulty. 


‘Risk Staffing Difficulty Team Size 
S| 32-Bit QuickDraw Oo————-——--—_O 
BI color PoascrptriterDever —§ E} $+ 
Inter Process Communications (IPC) C}—_—_—_1i# ———__L] 
Virtual Memory ee 
32-Bit Addressing Se | 
Outline Fonts 
Layout Manager 
New Finder 
2 Installer 3.0(Multidisk) 
- Database API 
<q | Language Manager a 
Script Manager Te 
Menu/Window Extensions” ~~, 
New Print Architecture 2 
File System Manager 
@ | DOS File System 
= | Network Booting 
& System Security 
% | New Graphics Architecture 
= Imaging Device Manager 
Risk Staffing Difficulty Team Size 
gil] tow Fully Staffed  WellUnderstood ‘1-2 Engineers 
& Ws Medium = Partly Staffed Partially Understood 3-5 Engineers 
HE High Investigation Not Understood 5+ Engineers 
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Quality and Testing 

s Reliability and compatibility 

a Functional and esthetic superiority 

= A feature set that benefits users directly or pushes forward our development platform 
= Managing perceptions given unavoidable incompatibilities 


Guaranteeing software quality is a continual challenge to Apple as our system software becomes more complex and 
runs on more varied hardware configurations. A less important but vexing problem is guaranteeing that quality 
software is perceived as such and that the inevitable application problems associated with system releases are not 
perceived by our customers as poor quality. 


Our notion of quality encompasses the assurance that a product works as advertised; is functionally and 
aesthetically superior; is of significant benefit to our developers, our customers, OF both; and is as compatible as possible 
with our application base. The primary burden of delivering quality falls on Product Marketing, Engineering and Testing, 
and Developer Services, and those organizations are committed to produce highly reliable, innovative software. 


Our customers’ notion of quality includes frequent new.functionality (delivered when we say we will), but primarily 
demands reliability and a system upgrade tar is problem-free. And because we-can-never guarantee complete 
compatibility with every Macintosh application and hardwate device’on the market—a source of confusion and 


3 s 


sometimes great inconvenience for our customers {and developers);—we,cati tiever completely met our customers’ 
expectations. a ae; Yi 


Given the reality of incompatibilities, we have to be sure that the value added-of new Services for developers and 
new features for users is worth the paifi, Where there’s a clear win, customers arid developers will see incompatibilities 


* 


as a price they’re willing to pay and ‘perceive the quality we aré offering. To that end, we shifted the system release 


policy from twice-yearly releases {o featuré-driven releases and consequently reduced the number. Interim releases will 


> 


support hardware and should have little irnpact-oh application compatibility (see System Disk Release Strategy). 


Beyond restructuring our release policy, we need to educate intemally at Apple (where the quality rumors always 
start), the press, and the public that incompatibilities do not necessarily mean poor quality. In educating we must be 
very careful not to blame developers, but instead emphasize the process of software development as making some 
problems unavoidable. Again, when great features are perceived as the trade-off for incompatibilities, the customers will 
not complain. 
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System 7.0 Transition and One-Megabyte Machines 


The new features of System 7.0 will cause Macintosh memory requirements to grow by 100-300K. While System 7.0 will 
be fully compatible with all one megabyte Macintoshes, larger software programs (like HyperCard) will not run in this 
memory configuration. To run adequately, Apple will recommend that System 7.0 be installed on machines with at least 
2 Megabytes of RAM and a hard disk. 


System 7.0 will be compatible with all Macintosh Plus, SE, SE-30, Il, IIX and IICX computers. Machines that use the 
68030 (or 68851 PMMU with a Macintosh II) will also have the benefit of virtual memory. Virtual memory will not be 
required to run System 7.0. 


Transition to 7.0 


To allow developers to create the best applications software for users, it is critical that Apple establish System 7.0 as a 
standard. However, with the large number of one megabyte machines in the installed base and because customers have 
asked us to maintain a low entry price point, transition to System 7.0 will take some time. 


- Transition Plan 
The trans ition to System 7.0 acrosg the Macintosh prdduct plan has several steps ns 


: : 2 
3 


= When System 7.0 begins shipping, it will initially be pa¢kaged with higher-end. configurations only (those with more 


eeeecee verse veersseseesoceeere re eee ly 
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Impact of New Features 

The new features that are under development for FY89 have differing impacts on users and developers. Some features 
will be immediately apparent to users (such as New Finder), while other features will not be apparent to users until 
developers take advantage of the feature (such as InterApplication Communication). The following chart is an impact 
spectrum for some of the new features in development. | 


Impact of Big Bang Features 
Group Affected 


Functional Area 
Operating | 
System 


Imaging 


Outline Fonts 


—_— 


Desktop a New Finder 


Services 
Database SQL API New Installer 
| Script Mgr ff Language Mgr 
fee Menu/Window Extensions 
System BE New Print arch 
Integration oe ot : 
Color PostScript Driver 
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Developer Impact 


The chart on the next page illustrates what the developer impact of each system software feature is likely to have. The 
effect is categorized using the following factors: 


Breaks Unclean Applications Certain applications that have failed to obey Inside Macintosh programming guidelines 


No Effect on Apps 
Free Functionality for Apps 


Write for Feature 


April 6, 1989 


will be incompatible with this new feature. 


This feature has no effect on existing applications and does not change the programming 
model. 

This system software feature transparently adds new functionality to the existing base 
of application software. 


Applications must be specifically written to take advantage of this feature. Often, these 
features will provide new application programming interfaces for the application to call to 
obtain the new services. The Easy, Medium, or Hard qualifier describes the relative 
difficulty associated with implementing the feature. 
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Developer Impact 


=| 
3| 
= 


Big Bang 


Investigations 


Breaks ‘Free Write 
Unclean No Effect Functionality for Feature 
Apps on App for Apps 


32-Bit QuickDraw 
Color PostScript Printer Driver é- 


Inter Process Communications (IPC) —— 

Virtual Memory 

32-Bit Addressing é 

Outline Fonts 

Layout Manager 

New Finder 

Installer 3.0 (Multidisk) 

Database API woe 
Language Manager erst eeecconrenneiren ro eeears 
Inter Application Communications nS ee etre aa ee SRN ica cecsebeacces 
Script Manager i sscnsbioceteocsesesece Saat aa: susasdavesstecsscareccencns B setae cates ae 
Menu/Window Extensions So Or ee ec: aes 
New Print Architecture €---~ rose po cen MCs 


& 


File System Manager ie eae es aaa a wovecerensccccorses 


a e % Po : 
. a %, % f e 
d 5, *° . Fy 
%, BY - £ 
y % 53 es 3 
e System datang,__ tersesemesecsevceensebefeccencncsenrsemebeorsssnemecsesoacsenseccseresineconness 2 ea ero 
ie ae 2 : ? 
?: : % Fy 3 ry 
etwo! i Spceshiesensasie ; 
: rf 2 ? > 
f 2 - 2 2 : 
. $ 3 ey 2 : ¢ 
System Security 4 jeececcwcenccvcce: ateccce wevmesscnnnnsinee (i) sa eveseennemysceneenenennnmmnsniesonenemeseenanenmeccrannssenserccnnarerneces ekeasbicsessese 
" 7 ” SG a 
4 "ee aw 2 2 f 
? 


New Graphics Architecture“. Sette ceca smrpttnneeennnnemmnnfcneeneene sea ep iediectansbitiataeaseecatee 
Imaging Device Manager TE eee ge Sent A cscs sta Ss adés chars cemimaimed basen Ja scnasesnesnns + iobteotemianscusnoasceseuracntsscctseesscsoness 


Note: The New Print Architecture is expected to break all shipping third party printer drivers. 
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Customer Impact 
No Impact No discernible impact to customers; primarily a developer feature. 


Improves Process/Visual This feature simplifies an existing process, has an improved user interface, or generates 


better WYSIWYG displays. 

New User Capability This is a major new user-oriented capability. 

Greater Flexibility This feature incrementally extends an existing capability or standardizes a capability to 
provide more user choice. 


Al 32 Bt QuickDaw ceo cee, 
= Color PostScript Printer Driver 
coo 


Inter Process Communications aro Oe eee 
Virtual Memory oe aa of i 
32-Bit Addressing wae a : é o one 
Outline Fonts 
Layout Manager 
en| New Finder . ae, - : 
& | Installer 3.0 (Midis) re ro et! 
yon Database API PS to: ae reereerny rn eee 
#4 | Language Manager — —Q—-—_--e-—_ 8 
Inter Application Communications Q-—— 
Script Manager EDEN (i, Cre 
Menu/Window Extensions ene neem ne ent enero {BY 
New Print Architecture a a a ia 
File System Manager Sener nernnninrrees es 
2 | DOS File System 
& | Network Booting 
SS] System Security a 
% New Graphics Architecture 
& Imaging Device Manager -2 
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Evangelism 


The objective of evangelizing systems 6.0.x is to ensure that developers have had time to test their applications’ 
compatibility with a version of the system that contains very few changes, except for those specific to new hardware. 
32-Bit QuickDraw has already been seeded and is expected to have quite a few third-party products developed for it by 
the time of introduction. 


The objectives of evangelizing the Big Bang release are: 

ws To ensure that applications exist at introduction that take advantage of the features we have planned. 

a To ensure compatibility of applications introduced in the next release with the future system requirements. 

 Toensure that key developers know about these projects in order for them to feel secure about Apple’s future 
software directions. 


At the Spring Developer Conference (May) we intend to throw open the doors to developers and announce all of the 
major developments that will affect them, along with dates. While we are interested in preventing the kind of media 
speculation that has occurred around the delivery of Presentation Manager, we also want to ensure that as many 
developers as possible that need to know about the project will be involved. 


eid uted be base cmrecae eeu | ees 

System Software: An Overview 6f Coming Changes ; 
Enhancements to the Macintosti Opérating System" 

InterApplication Communications {<7 

Window and Menu Manager Extensions .....--..., * 

Text services (Layout Manager, Qutline Fonts, Language Manager) a 

The International Macintosh: Changes to the International Software Archijécture 

Future Output: Printing in 1989’and Beyond : f : 

32-Bit QuickDraw and LaserWriter Driver 6.0 

Standardizing Sound on the Macintosh “~""" i i ; 

New Finder and opportunities for third-party.expansion; new Installerincan.co:sno! 

Database API 

Compatibility 

Support and documentation 

System Software Futures: Beyond 7.0 


System Software Feedback Forum 


: ¢ 
ened 


There will also be a small feedback forum to discuss changes to the video architecture and slot manager. Discussion of 
the Finder is still under consideration. 


We plan to distribute technical documentation on Big Bang features at the conference. Actual seeding of Big Bang 
software will not take place at the developer conference. Evangelism and Product Marketing are finalizing plans for Big 
Bang seeding. To avoid problems with potential schedule slips, we will announce a Big Bang delivery date of at least one 
quarter later than our internal schedule. 


While regular development system updates will be sent toa select number of developers chosen by Evangelism, it is 
expected that the initial Beta version of the system will also be distributed to all certified developers. 


Approximately two months before Golden Master, Apple should host a “Show Apple” technical demonstration 
where the original developers come and demonstrate their versions of applications using the new features to Product 
Marketing, Evangelism, Engineering, and SQA. This demo is expected to motivate both developers and engineers in 
putting the finishing touches on all products. 
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Golden Master will be shipped to all Developers approximately one month before general availability. 
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Marketing and Introduction Plans 


Impact of System Software in the Market 


It is important to recognize that unlike new hardware products, new system software affects virtually all of the 
installed base. And yet historically, Apple System Software product introductions have been extremely quiet. The 
impact of this has been to leave many developers and users in the dark as to exactly what we are doing with a new 
release. This will change in 1989. Every new release of system software will be clearly articulated to the press, users, 
developers, and others through a variety of media. This will also give us an opportunity to reinforce our competitive 
advantages. 


Marketing System Software 
Macintosh System Software Product Marketing, Evangelism, and the Marketing and Sales channels need to cooperate in 
getting information about system software out efficiently.-System Software Product Marketing will provide tools to 
various Apple groups so that they cafi al&6 deliver directional and product'specific presentations: 


3 
> 
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Positioning of System Disks 


0 


Minor system disk introductions will accorfipany Apple hardware introductions. System Software Product Marketing 
and CPU Product Marketing will jointly participate in any press sneaks or produgt annouricements. We will explain the 
content of each system disk as well’as Who needs to/upgrade to ensure that the system disk is positioned correctly. 


Announcement of the Big Bang-Reieasé eee 


The first announcement of the Big Bang release will take place at the Spring Developers Conference (May). Since it will 
be nearly impossible to “nondisclose” all 2500 developers in attendance, our announcement will be public as of May. To 
contro! the information flow, Apple will hold a press conference concurrently with the Developer Conference. To 
prevent a Presentation Manager “preannouncement” situation, we will announce that we expect to release this system 
by the first quarter of 1990. 


Intemal target completion of this system is expected to take place at the end of October. If the product slips much 
past that, it will be better to introduce i with a Press Conference at MacWorld than to release it between late December 
and early January. We will be expecting to involve the same key third-party developers in the introduction, perhaps 

- having another “Mini-Tradeshow” like that held at the Mac Il introduction. Brochures spelling out the advantages of 
the new system to our customers will be distributed. 
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Competitive Position 


We are frequently asked to answer the question “What will Apple do to catch up?” This is especially disturbing when the 
question is asked from within Apple, because the simple fact is that at an overall system level, Macintosh is still ahead 
and will stay ahead. 


The advantages the Macintosh offers produce a superior user experience; this is the key to the competitive battle. It 
is also true that on a feature-by-feature comparison, Macintosh is ahead in some areas and behind in others (operating 
system services is one area where we do have notable weaknesses—we are doing detailed analyses across the board with 


Market Intelligence). However, to win in the market, we must take the higher ground. It is our overall system 
advantages that are furthest ahead and most leverageable. 


Nine Unbeatable Macintosh Advantages 


A hallmark advantage of the Macintosh. 


System Integration 3 ‘ \ é f 7 
is the seamless integration of applications, hardware, and data. Examples of this 


are AppleShare servers, which are accessed in the exact same manner as local’storage; EaserWriters, which are accessed the 


same way as ImageWriters and even Fax modems;'the Clipboard that allow’s data exchange between almost all 
applications; keyboards and monitors that offer plug-and-play setup. Ng other system offers this level of integration. 


The benefit of system integration is iHat-Macintoshusers can do more with-less-effort and support. 


a 


Control of both Software and Hardware 

No other personal computer manufacturer controls both the system software and the CPU hardware. The advantage is 
that when we want to offer new hardware functionality, we can ensure that it is well integrated into the environment 
with system software. This integration capability means that if we want to extend our sound hardware, for example, 
we can also create system software that allows developers to seamlessly integrate sound into their applications. In the 
MS-DOS world, the mainstream hardware environment can only evolve when Microsoft and the clone makers choose to 
support it. To users this means that Macintosh can evolve more dramatically and more quickly. 


No Competition with Applications Developers 
Apple does not generally compete with applications developers. This means that developers have every reason to 

- provide standard support for our Macintosh software extensions. In the Microsoft world, applications developers also 
compete with Microsoft, and so applications developers may wish to do nonstandard extensions in their applications 
(which violate Microsoft-specified OS/2 conventions) to better compete with Microsoft's applications. Users then 
suffer the consequences of applications that may not work well together. 


Product Line Range 
Macintosh functionality is available from a relatively inexpensive one-megabyte 68000-class computer. OS/2 requires a 
very fast ‘286 or a °386 machine with 4 megabytes of RAM and at least 40 mieagbytes of hard disk storage. UNIX 
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platforms require even more hardware. This difference means that not only does a Macintosh do more, but it is also 
available in a low-end platform costing less. | 


Upward Compatibility 

Macintosh applications that run on our low-end machines (almost all of them) run even better on our high-end 
machines. In the IBM-compatible world, low-end MS-DOS applications actually perform worse in the high-end OS/2 
environment (this is due to the limitations of the “compatibility box"). The benefit to Macintosh users is a superior 
growth path. 


Finder 

The Finder allows Macintosh users to perform complex system tasks like file copying, moving, deleting and program 
launching in an intuitive manner. No other system provides this level of access to system functions. OS/2 and UNIX 

environments require the user to have far more sophistication. While those environments may eventually solve those 
problems, Macintosh users continue to have a superior system environment. 


HyperCard 

HyperCard is an unmatched advantage. HyperCard offers users unique specialized tools and an accessible development 
environment. The relative ease of developing HyperCard:stacks means that more people can develop more tools for 
Macintosh. HyperCard means that users can more easily get the specific tools that are required for,their environment. 
Macintosh Enthusiasm : : en ; f & a 
Macintosh users are evangelical. Wé knaw-of no othe? product that é¥okes such loyalty. Users have fun with 
Macintosh. orn \ eo # 
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Issues 
These are some of the issues we will need to address. See Spring Developers’ Conference materials for additional issues: 


ws Do we have the infrastructure in place to support all developers on all of the new features? 
ws What will we do for Blue in 1990? 
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32-Bit QuickDraw 


Brief Description (Product Manager: Laurie Girand) 
Extensions to QuickDraw that support drawing with up to 16 million colors, instead of only 256. 


Schedule 
Spring '89 release 


Benefits to Users 
= With a new video card, the screen will no longer be constrained to 256 colors at a time. 
@ The price of high-quality color will be driven lower in the Macintosh market. 


Benefits to Developers 
= Developers will be able to support applications with access to over 256 colors in a device-independent fashion. 
Third-party devices will proliferate, taking advantage of the consistency in the programming model. 


= 32-Bit QuickDraw will substantially raise the competitive stakes Of color in the personal computer market since 


Display PostScript and NeXT Step have-yet.to.demonstrate this; capability 


w Apple will be able to continue positioning the. Macintosh as the leader in high-qual ity’ persenal-computer image 


Functional Objectives (by priority) ‘ i i? 

1. Support 24 bits of color on the-scréen, with an additional eight-bit pad byte. 

2. Design new Monitors control panel. 3 ; ; Zé 

3. Support the 16-bit subset. 8 nee’ 2 

4. Fix regions so they don’t fail under.low memory conditions. a 
S, Put in hooxs for hardware acceleration done by standard coprocessor. ~~ 
6. Support the alpha channel byte. 


Dependencies and Assumptions 
@ The Palette Manager will be revised. 
w Sufficient PQS resources. 
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Color PostScript Printer Driver 


Brief Description (Product Managers: Laurie Girand/Michael Hopwood) 
Development of a printer driver for PostScript devices that support color. 


Schedule 
Spring '89 release. 


Benefits to Users 
w Users will have a single driver they can use for interfacing between the Macintosh and color PostScript printers. 
= This will be the first Apple-endorsed mechanism for achieving color output from the Macintosh. 


Benefits to Developers 
w Color PostScript printer developers will be supported on the Macintosh without having to design their own drivers 
or having to write PostScript directly. 


Benefits to Apple 
= Apple's lead in color appli ications is will be bsg enhanced ‘ic the rciata of color p pring 
s High quality color output will become a pic near 


Functional Objectives (by priority). 2 é ; 

1. Work between applications supporting color ‘GralPons aid printers SUPPO", lor poiscrit 
2 Work with all applications. ‘ ; é 

3, Support grayscale printing on. current‘Apple Laser Writers ; f 

4 Make OR transfer mode (unsupported by PostScript) al for Draw | yf 

5. Support 32-Bit QuickDraw printing. renee a 


Dependencies and Aasnigde. _ 
e Will runon 1 MB machines 
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InterProcess Communication (IPC) 


Brief Description (Product Manager: Steve Goldberg) 


IPC allows one application process to send data to another application process on the same machine. IPC is engineered as 


an extension to the Macintosh Event Manager. 


Schedule 
Specification: March '89; Alpha: May '89. 


Benefit to Users 
= Applications that work together will become more pervasive 


Benefit to Developers 
a Developers can construct applications that use the services of another application. 


Benefit to Apple 
In addition to providing much negded operating -ayatén pai, IPC ‘also provides the: a for both inter- 
application communication and user se 


Seveee eevee eK TEN eeee Teer T TTS TO TTT pi PPPAALEREAA ALE ARKO RLAE RAND 


eset Objectives (by priori)” ae 
1. Delivery of messages from progess to process in same ‘thachine. 
2 Process name/port registration’ for difectory lookup. 4 
3, Message delivery between processes in different: machines. 
4 IPC services available to non spolietion endities; 


Assumptions and Dependencies ai 

s InterApplication Communication afid-User. Scripting require IPC facilities ~ 

w IPC requires a MultiFinder environment 

w Engineering resources from N & C will be available to complete the networking component of IPC 
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32-Bit Addressing 


Brief Description (Product Manager: Steve Goldberg) 
Permits Mac lI-class machines to address more than 8 megabytes of memory. 


Schedule 
Aurora ROMS and all following CPU ROMs will be 32-bit clean and support both 24- and 32-bit worlds, selectable on 
startup. Big Bang disk will run in 32-bit mode. 


Benefit to Users . . 

@ Opens architecture to 128 MB of System RAM and 4 GB of logical address space. 

= With more memory or VM, users can work with larger amounts of data. 

e Users will eventually have access to a new class of high-end, memory-intensive applications such as artificial 
intelligence, graphics, and simulation software. 

= Users will eventually be able to run more applications in a MultiFinder environment. 


a 
acalawieierereuaceiecareie:s: eleielereleleiece;piecerece: ne'er e 


Benefit to Developers = 


| 32-Bit Addressing permits full access to NuBus Super Slot meméry. 


ov 


Benefit to Apple ae a \ a, 
Gives credence to our high-end products (4-square/F19) since processes can now have arapplication space greater than 8 
MB. 32-Bit Addressing also supporis-high-end systems with more than 8 MB,Of physigal RAM. 


Functional Objectives (by priority)...” 
1. Run more applications. Pes a 
2. Run more applications in a given physical space. 

3, Run applications greater than 8 megabytes. 

4 Protect one application space from another. 

S. Support applications that are not 32-bit clean. 


Assumptions and Dependencies 

= Hardware upgrades will allow 68020-class machine owners to move to virtual memory/32-bit addressing machine. 
= Apple will provide tools and information to push developers to 32-bit clean applications. 

ws The product should strongly encourage developers to write 32-bit clean applications. 
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Virtual Memory (Yellow Pages) 


Brief Description (Product Manager: Steve Goldberg) 
MultiFinder extensions that allow users to work with more applications and data that can fit in RAM by swapping 
inactive parts to disk. 


Benefit to Users 

w Software solution to expensive RAM upgrades 

ss Users can run more applications simultaneously and work with larger amounts of data. 
w Users can run applications larger than available RAM. 


Benefit to Developers 
= Developers can write applications larger than 8 megabytes. 
w Developers are relieved from having to develop custom virtual memory systems to handle large amounts of data. 


Benefit to Apple 
Gives credence to our high-end prdducts (4 Squa' 
Also VM legitimizes the use of the: 680 30 microprocessor ig our nevjest machines. 


{eee sereeweveseseeerewerseesereersreneet 


Functional Objectives (by priority) ~ 

1 Run more applications. i 

2 Run more applications in a given physical spaces, F 
3. Run applications greater than 8 megabytes. ‘ f 
4 Protect one application ae from another. : f 


Assumptions and Dependencies Sere é 
ws Presence of VM does not change thé:application: tidel Sosannanaaunannnnnned 
# Hardware upgrades will allow 68020/68030-class machine owners to move to sul memory machine. 
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Outline Fonts (Bass) 


Brief Description (Product Managers: Laurie Girand/Jim Gable) 

Development of an outline font system on the Macintosh. The current Macintosh model stores text characters as 
bitmapped fonts. The ability to produce fonts algorithmically from outlines allows fonts to be manipulated 
mathematically. 


Schedule 
Alpha in January. Beta and Final dependent on Big Bang. 


Benefits to Users 

= Bass delivers the best rendering of type on monitors and printers at any resolution. Therefore, the user should be able 
to obtain very high quality output without paying the prices of PostScript. 

e Because it creates an open-font format, hundreds of typefaces should be available to Macintosh users over time. 


Benefits to Developers Soeeubekee eee 
e@ With the open-font format, any vendor will be able to provide high-quality fonts to the "Mac marketplace. 
w= There will be a single font standatd so that each developer is not dependent on defining or buyibg his own. 


geoweweeee Ves eeeererecceeereeerer ee 


2 


Benefits to Apple oe ma ae ff 
m= Because it is being created in-house, Apple-will be able to’enhance and improve thie Mac,dutline font technology in 


future System Software releases..." 


= Fonts rendered on QuickDraw printers will have the same high quality as thdse on PostScript printers, at 
significantly lower cost. : ‘ : i é : 


Functional Objectives (by priority) bad sada e 

L Run with significant backward compatibility" 

2 Printing support. 

3, Development of an open file format with wide third-party support. 
4 Reasonable support for developers who want to encrypt their hints. 


Dependencies and Assumptions 

e Will t run on 1 MB machines? 

aw Requires extensive testing, as fonts are used in all applications. 

ws SQA needs to develop test plan. 

= Outline fonts will be substituted for bitmapped fonts. Developers do not have to rewrite. 
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Layout Manager (Boffin) 


Brief Description (Product Manager: Mike Wallace) 
Allows the laying out of lines with special effects such as ligaturing and kerning in a device-independent environment. 
Such functionality will be optimized for device-dependent environments. 


Schedule: Alpha 
May ‘89. 


Benefit to Users 

a Bass text on the screen will be laid out in a more attractive manner. 

« Printed text will be laid out identically to displayed text (or improved). 
w More international users will have line layout support. 


Benefit to Developers 
@ Developer will no longer have to put line layout into their packages. 
ws Font developers will be able to, differentiate their products based.on.added features... nucsny 


~ 
Jigen tit eoaeeamonnnentorier : or AAARERA AERA RARASaARnRt ty 
3 ‘ 


= Apple will improve its competitive advantage.of WYSIWYG. i... ia. 
s More CPUs will be sold into international markets préviously unsupported by WYSIWYS. 


Functional Objectives (by priority) ? 
1. Provide line layout support that uses, new Bass fonts. 

2. Provide high-level line layout support to applications. : 

3. Provide low-level line layout Support for.Mae’graphics arid printing. i 
4 Ensure support for international‘eases not currentlytiandled by the system. 


Assumptions and Dependencies 

a Will work in both Pink and Blue environments. 

s Bass compatible with international requirements. 

e Ginsu. 

= C++; layout core will be object oriented. 

# Unicode and graphics issues resolved in Pink in same timeframe. 
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New Finder 


Brief Description (Product Manager: Charlie Oppenheimer) 
Next generation Finder that increases ease of use through more powerful disk organization and document location 
mechanisms, user customization, and direct integration of today's stand-alone utilities. 


Schedule 
Feature Set: 11/88; Beta: 5/89, Final: 10/89. 


Benefit to Users 

a Easier use through greater consistency and more intuitive access to fonts, desk accessories, network resources and 
control panels. 

s Tools to quickly find and organize documents. 

w Background copy operations. 

ws Context-sensitive help system. 

a Greater ability to customize the appearance of Finder objects. 

Ti veeeaipee 8 a 

Benefit to Apple pre r i. rae 

s New Finder will revitalize the Macintosh’s €ase Of ise-and reasseit"Apple’s lead in irinovative user interface 
technology. : en ~ rs ee 

e Anextendible Finder provides an.easiér development model, for adding our opin services and ensuring interface 
consistency. nee : ; a ¢ 


Functional Objectives (by priority) a é i ; 
Integration of Font/DA Mover-functionality into the.Pinder interface. i 


Integration of Chooser and Control Panet-into thé direct manipulation Pinder interface. 

Standard interface for device connections currently done by various software components. 

New volume Mount/Dismount model. 

Customizeable Apple menu for faster, easier access to favorite files. 

Built-in help facility. 

Integration of Backup functionality into the Finder. 

Capability of having multiple views of an object by having copies of an object that point back to the original. 
Provide capability for the user to customize views. 

. Intemal and public program interface to allow external units to use Finder services and to provide utilities that 
integrate naturally with the Finder (such as backup). 


BIO mPN AM hw me 


Under investigation: filtering capability, access privileges for local folders, stationery, drawing on Folders. 


Dependencies and Assumptions 
s Target platform is 68000, 1 MB Macintosh; MultiFinder standard. (Is this viable?) 
= Desktop Database and Extended Catalog services from file system group will be available. . 
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Installer 3.0 (Multidisk) 


Brief Description (Product Manager: Ken Feehan) 

A second generation “Installer” with the capability to read information from more than one source disk enabling the 
installation of Systems larger than 800K. The new Installer will simplify the process of installing the “Apple 
recommended” system files, and will provide power users with complete control over exactly what is installed/updated. 


Schedule 
MultiDisk Installer should go alpha before December '88 May ship with system 6.0.4. 


Benefits to Users 

a “One button” approach to the installation of Apple’s System Software. 

= The new Installer will incorporate built-in intelligence, freeing the user of numerous choices necessary in the past. 
e The MultiDisk Installer will also provide users with more information about exactly what an Installer does. 


Benefits to Developers 7 
s Ability to license the MultiDisk Jnstaller-for-their-owt use. 


: 
: 
: 


gevveedeveveeeeveveeereeewesvevereewedt H AO AMERRER ARERR RRA NEDO OONE OS 
’ 


Benefits to Apple it cae 
s Apple will no longer be constrained by the 800K Jimit. H 


of ont 


w Apple will be assured that users: will have a complete system folder rich in printer‘drivers, fonts, utilities, etc. 


Functional Objectives (by priority) ‘ H 7 

1. Provide the ability to grab files-from more than one source disk. f i 

2. Include ability to poll the ROMs and SCSI bus to,inquire about hardware,availability. 

3 Further include capability to use this information to decide what systerh files shguld be installed. 

4, Provide capability to decide whether.the system files ‘found in the System, Foldes (an existing Macintosh system) 
should be updated with the most recent versions of system software, or to create and install system files ina new 
System Folder (new Macintosh system). 

5, Provide an Installer with a straightforward interface. 

6 Provide a modular installer offering two levels of user interaction. 


7. Allow access over an AppleShare server and update of a local Macintosh booted from the target disk. 
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Remote Database API 


Brief Description (Product Manager: Michael Wallace) 
Toolbox extensions that give applications standard access to remote databases. 


Schedule 
ERS: 1/89, Alpha: 5/89; Final: 10/89. 


Benefit to Users 
@ Users can access remote databases in a standard way with a consistent user interface from any supporting 


application. 


Benefit to Developers 
a Developers can easily add database access to their applications 
@ Remote Database Access allows developers to access the i aa capabilities of various SQL databases. 


_ Benefit to Apple i : 

Remote Database Access improves Apple s ability to compeje in mul vendor environments by allowing applications to 
access popular database servers. Macinigsh becomes ba sy personal gomputer to nee data across any database 
management systems. 


Functional Objectives (by ahaa 
1 Implement Data Access Manager.routines. 
2. Define and implement higy-tevel query so API, . 


Assumptions and Dependencies. < 
a Remote Database Access is dependent onthe €L/T’ ae 
= Seperate CL/1 language from the API. 
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Language Manager 


Brief Description (Product Manager: Michael Wallace) 
Standard application interface for spell-checking, thesaurus, hyphenation, and other utility services. 


Schedule 
Specification: October/November °88; alpha: May '89; Ship: October 89. 


Benefit to Developer 
= Easy, standard way to provide spell-checking and related services in all applications. 
ws No need for each to developer to re-implement these services on their own. 


Benefit to User 
« Ultimately, this will provide for spell-checking and related services in all major Macintosh applications software. 


Benefit to Apple re ca: 
= Sameasbenefittodevelopers. | i 


Ae P AEE RREAE AER EERO RRR AERIAL ES 
. 


1. Simple programming interface that all. applications can.call to obiditr high-level text services with user interface. 
2. Simple programming interface fot all service-providers (spell-checking, thesaurus, hypheriation, and so forth are all 


3, Low-level interface for appl ications. to access text Services ditectly. 


Priorities 4 ow ’ 

Both functional objectives are required to ship this feature” 

Assumptions and Dependencies 

@ Service modules will be third-party products available separately from applications. Evangelism of these products and 
the application interface will be needed. 

= Service modules will use the interface as the exclusive means to talk to applications so that all applications and service 
modules will work together the same way. 

w May ship with bundled dictionary/thesaurus to promote usage. 
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Script Manager 


Brief Description (Product Manager: Michael Wallace) 

‘The Script Manager Project comprises the Control Panels (Keyboard, Map, International), the DA Key Caps, and the core 
script manager itself, which provides a standard application interface to international formatting utilities (sorting, 
dates, time, number formats) and a framework for writing systems such as kanji or Arabic, called scripts. Changes 
include enhancements to the International CDEV, Map, Key Caps, and the core Script Manager. 


Schedule 
Specification: Feb ‘89, Seed: 3QF Y89; Ship: October °89. 


Benefits to Developer 
@ Standard way to provide script services in all applications. 


Benefits to User 

a International CDEV provides more © cen among, Gilflerent international ¢ customization resources and limited 
editing of the resources. a eae 

s Key Cap’s interface changes to rake dead Keys visible ig low es user to see Se the , charaer er sequences to create 
gecented characters, 900 = _Cgreeseteseerererrrrerereseerereerenn , ngs a 

s Map changes add irregular time zones and better. human ee 


Functional Objectives (by priority)” : 

1. Customization options in the Inteftiational CDEV. 

2 Additional characters for the Maciniésh characier set. 
3 Dead key support in Key Caps; ; |; 

4. Irregular time zone support for. Map. Rae 


Assumptions and Dependencies: 
# Mover support for international resources. 
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Multiple Script System 


Brief Description (Product Manager: Michael Wallace) 

Allows multiple script (e.g., Roman, Arabic and kanji ) installation and provides a standard application interface for using 
multiple scripts in a document (provides for multiple scripts for file and icon names in the Finder). The MultiScript 
project includes the multiscript system software and a script system core to help speed and standardize script system 
development. 


Schedule 
Specification: 2/89, alpha: May’89; Ship:10/89. 


Benefit to Developers 
we Standard way to provide multiple script services in all applications. 


Functional Objectives (by priority) 


Seeeeeeverere rere Terr eer eee TT TN 


3, Scripts that function in a multiple script environment ‘, 7 
4. Finder/File System support to provide multiple'scripts for‘object names. ri 


Dependencies/Assumptions , 
w= Requires Finder and File System SUPPOFt wv 
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InterApplication Conimunicayens (Diet Coke) 


Brief Description (Product Manager: Steve Goldberg) 
Automatic data-sharing between Diet Coke-aware applications. Diet Coke allows documents to always contain the 
most recent update of information originating from another source. | 


Schedule 
Project is staffed; prototyping stages; alpha: May ‘89; Beta: 3QFY89. 


Benefit to User 

Automates repetitive cut-copy-paste. 

Documents always contain the latest information even across networks. 
User can leverage multiple applications to solve problems. 

Networked users can work collaboratively on joint projects. 


Benefit to Developers 


zs High-level mechanism for interApplication. communicate — application developers to. sreate applications that 
work together. : 


Functional Objectives (by ororigy ae 4 a 
1. Automatic transfer of informatipn tiGigh *publiong i # 

2 Persistence of links. ‘ ‘ 
3, Support application-initiated link creation. ; 
4 Support publications residing on.a'fite server. 

5, Link Management and Map. ; 
Dependencies and fesriapt ie . 

s Applications must be written to take advarilage of Diet Coke. 

w Diet Coke does not fundamentally alter the programming model. 

= Target platform is a 2 MB, hard disk machine running MultiFinder. 

s Expanded data types will provide richer forms of transferring information. 
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Menu/Window Extensions (Glass Plus) 


Brief Description (Product Manager: Michael Wallace) 
Glass Plus enhances the window and menu managers to provide standard tear-off menu capability and toolbox support 
for floating windows. 


Benefit to Users 

e System-wide standard capability to tear off menus. 

a Encourages standard interface for objects such as TearOffs and Floating Windows. 
sw Better supports Large and Multiple Monitors. 


Benefit to Developers 

w= Standard toolbox support for creation and management of floating windows. 

w Glass Plus provides standard integrated ways to add floating windows to applications. Developers don't need to 
solve the intricacies of floating windows implementation. 


Benefit to Apple LN eee MOT : a are 


e@ Glass Plus must be coordinated with the Video Overlay project which also involves significant changes to the 
window manager. | : 
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New Print Architecture (Ginsu) 


Brief Description (Product Managers: Laurie Girand/Michael Hopwood) 

A unified printer driver mechanism to support all past and future Apple printers, and some third-party devices as well 
through selective technology licensing. Greater functionality will become available including background printing across 
all devices, better paper handling, differing page orientation, custom page sizes, and so on. 


Schedule 
Alpha: April 1. Ship with Big Bang. 


Benefits to Users 

= Because developers will be facing a more consistent programming interface, users should ultimately face a more 
consistent printer interface. 

@ More devices, including film recorders and plouers, will ultimately be available for consistent use with the 
Macintosh. 


Benefits to Developers gesnnneccnnnneecnnencneennnt fd i 
a Developers will be presented with a a consistent nt prograniming interface loa acesing gies. 
@ Access to modifying the Page Seu and. Print. dialogs.is a sla a manner... ? 


Benefits to Apple a i J f 

w The lead time for printer driver tev me unt cen was over a an yea ald be reduced to a few 
months. 

w Common functionality for printing val be kept i in a modal form, sia ness the maintainability of 
printer drivers. 

= Support for significant third- pay pe eer fulfil oy dgaieaies wil become a A realy 

Functional Objectives (by priori 

1. Work with applications that are not guilty of “print crimes.” 

2 Support all non-PostScript printers in first release. 

3 Support PostScript printers. 

4. Support key film recorder, key low-end color printer, and key plotter. 


Dependencies and Assumptions 

Dependent on features of New Finder (such as Chooser modifications) and Bass. 
Dependent on memory model. 

Good developers should not have to rewrite. 

‘Will run on 1 MB machines. 

Will break all shipping third party printer drivers. 
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File System Manager (External File System) 


Brief Description (Product Manager: Steve Goldberg) 
The File System Manager (FSM) introduces a new architecture that supports attaching multiple file systems to the 
Macintosh Operating System. 


Schedule 
ERS: 1/89; IRS: 11/88; Alpha: 3QFY89; Beta: 4QFY89, Ship: Oct 89. 


Benefit to Users 
a Users will benefit when Apple or third parties deliver well-integrated file systems so that foreign volumes can be 
manipulated in standard Macintosh ways. 


Benefit to Developers 

a Application developers can write to a standard “virtual” file system. 

= Third party file system developers have means to tightly integrate their siaare into Macintosh architecture. 
= Developing a file system is easier-due-to-better- interface and utility-services... : 

w FSM defines an architecture tha is atari to span us ges services such 2 as s database access. 
Benefit to Apple eo 

= Same as benefit to developers. val ke 


Functional Objectives (by priory) : 

1. File System Installation, Initiation, aid Call Dispatch, 

2 DisklInit rewritten to support File System Manager. F ; } 

3, Standard utilities (cache a parsing; sa coeclae: Bree manipdation accessible to all file systems. 


Assumptions and Depeadenies. 

ws Project needs adequate staffing. 

ws DOS File System Project requires FSM. 

a External FSM architecture is supported for compatibility reasons. 

= FSM architecture and services are published for third parties. 

s AppleShare should be converted to operate under FSM to make the file system more reliable. 
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Network Booting (Investigation) 


Brief Description (Product Manager: Steve Goldberg) 
Investigation only. A new ROM feature will enable future Macs to boot up and run without access to either local hard 
or floppy disks. 


Benefits to Users 

= Macintosh users with access to this feature will not need to configure their own System. 
sw Updating their local System Folder with newer version available over the network. 

ws Macintosh computers will have a lower cost. . 


Benefits to Developers 
= By entering these new markets, Apple creates new opportunities for third-party developers to create special 
software and hardware for the education, banking, general purpose (exhibit type), and government markets. 


Benefits to Apple ce 

a Ability to ship a lower-cost Maeintesh-that-offers-cuistomers a high level.of.media.and. data. security. 
s Allowing for the operation of 4 diskless Macintosh, 

Assumptions and Dependencies.” , 

a Network Administrator software™is written. + 

a The Spin product is brought to’ market. 
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System Security (Investigation) 


Brief Description (Product Manager: Steve Goldberg) 
investigation Only. Blue Operating System enhancements that allow a user to protect documents from unauthorized 
access. 


Benefit to Users 
= Helps prevent unauthorized access to sensitive information by casual snoopers. 
@ Well-integrated Apple solution in existing user model with logical extensions. 
_ @ Optional security—users not desiring system security are not bothered by its availability. 


Benefit to Developers 
ws None perceived. 


Benefit to Apple | 
System Security addresses a major Macintosh shortcoming that slows penetration of some market segments including 


corporate, defense, and government. System Security, however, will Tidt provide absolute security of trusted systems. 


1. File Cabinet Security—user should be-able fo seléttively secure tertain documents-and folders while leaving other 
items unprotected. ieee ‘ fof 

2 Asingle password gains access.to all protected. items; uset does not have torenter separate password for each 
protected item. Less ; : é ¢ 

3, System Security Architecture’is multistiered permitting the addition by third parties of higher-degree security 
solutions. ‘ i oe s f j 

w System Security design should not promote the development of generalized cracking tools. 

System Security functionality should be fully exportable to foreign countries. 

= Third-party developers will provide solutions for situations requiring higher degrees of protection. 


a ThirdProtection model should coordinate with AppleShare and Personal AppleShare models. 
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New Graphics Architecture (Skia) (Investigation) 


Brief Description (Product Manager: Laurie Girand) 

Significant extensions to QuickDraw with a QuickDraw-like interface. Skia will provide resolution independent graphics, 
a new curve primitive, fancier typesetting commands, transformation routines to handle primitives and fonts, 
acceleration support, and comprehensive error detection and recovery. 


Benefits to Users 

w= Transformed graphics will be handled consistently across all applications. 

= Awider variety of output devices will become available, since the drawing model used for the screen can also be used 
for the printer. 

s Finally, significant hardware acceleration will become a reality. 


Benefits to Developers 

= Developers will have the option of writing to new graphics features. 

a Handling of superior graphics aaaaeicds ina consistent manner. 

Benefits to Apple 

ws New applications, with éiianads Ld functionality, OF. a 2 pens will be. san aia ope Macintosh, raising 
the desirability of the platform; i ¢ 


Functional Objectives (by ptioriy~ 

1. Transformations of fonts and penaives: 

2 Hardware acceleration. é rd 
3 Resolution independence in sjsiem and uae, and haiti capability. ¢ f 
4 New curve primitive. ae é H 

5. Error detection and recovery. a 

6 Fancier typesetting commands. 


Assumptions/Dependencies 

QuickDraw-like interface. 

Virtual memory handled by someone else. 

Printer drivers done by Print Shop. 

C compiler is substantially improved. 

The two additional people needed have not been hired. 

Developers must write for new functionality. Some QuickDraw calls may draw slightly differently. 
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DOS File System (Investigation) 


Brief Description (Product Manager: Steve Goldberg) 
Desktop and application access to MS-DOS and OS/2 volumes. 


Schedule 
Design: 2QFY89, Alpha: 3QFY89; Ship: Oct ‘89. 


Benefit to Users 

@ Easily move information between MS-DOS and Macintosh environments. 
w Manipulate PC disks just like Mac disks—same tools and ways. 

« Direct import and export of PC data to Macintosh applications. 

w No intermediate step of Apple File Exchange. 

a Greater reliability than Apple File Exchange. 


Benefits to Developers 

m= Standard interface to “virtual” fite“system:~ i 

a Easier recognition of PC docurhents out file types. : 

w Developers who create application: ernie ‘on both: aos mil es ‘by the’ yeh to, develop a single 
document format. oa ee ae F : 


Benefits to Apple : . f ‘ 
a Apple's PC file system software will simplify Apple’ s at y competing ind ‘multi-yendor environment. No longer 
will a media format barrier die users of different machines from excHanging gata 


Functional Objectives (by ity 

1. Read/Write access to PC volumes’ iteuchia eee +Fs eicdeee 

2 Standard desktop access to PC volumes through the Finder. 

3, Support for Mac-specific file information such as resource forks, longer file names, Get Info comments and Finder 
Information. 

4 MS-DOS disk initialization integrated into standard Disk-Init Package. 

5, Ability to assign Mac application and document type information to PC files. 

6 Support for both FDHD and PC 5.25-inch drives. 

7. Desktop database support for PC volumes. 


Assumptions and Dependencies 

w Current functionality in third-party products will be taken into account. 
w Target platform is 2 MB machine equipped with FDHD. 

ws Requires File System Manager and HFS Utilities. 

w Functionality and quality are more important than performance or size. 

= New version may be necessary when Microsoft creates a OS/2 file system. 
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Imaging Device Manager (Investigation) 


_ Brief Description (Product Manager: Laurie Girand) 

Investigation only. Integrates Macintosh graphics input by providing access to composite video in the Window 
Manager and by defining a new, more complete, flatbed and real-time scanner interface that enables image analysis. 
Supports SEG projects that will ship in FY90 and third-party devices. 


Benefits to Users 
= Scanning and overlay technology will be as well integrated with all applications as Apple’s current printer drivers. 


Benefits to Developers 

= Applications developers benefit but remain device independent. 

= Device developers will sell more devices when more apps are supported. 

= New market opportunities will become available in areas of character and pattem recognition and image processing. 


Benefits to Apple 

e More developers would be ici ask to-a-Stable. platform a innovative. products. for. what would otherwise 
be a riskier market. i 

w Will extend Apple’s sane! oyer the.competition.in bimapped graphics. 

s Apple will substantially increase: Fits visibility. as.a.multimedia platform. 

@ Providing a mechanism for image anhfsis ne as chatacter recognition, Apple wit inproe "he likelihood of success 
for such new technologies. 

w System Software will prevent the iaemnedl design of i image! ‘input and display’ by providing a ground up architecture, 
substantially improving gia meee :of a device oe / ; 

Functional Objectives (by priority)... ? j i 

1. Develop a Chooser-selectable, maximym- olor manera and interfice for vatiable resolutions that can be 
accessed from all applications. 

2 Support real-time scanning devices. 

3, Support plug-in modules for character or pattern recognition. 

4. Window Manager should be rewritten to support video in window. 

5, Support translations from alternate color models. 


Assumptions and Dependencies 

aw Third-party device designs will also be taken into account. 

s Driver definitions will be published to third parties. 

= Code will be written in a portable fashion, so as to be transferrable to Pink. 
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More Projects (Investigations) 


Esprit Support (Product Manager: Ken Feehan) 

The Esprit hardware will require changes made to the system software in order to support Esprit features such as Sleep 
and battery control. Esprit also contains new ROMs which will require system patches. Esprit and System Software 6.0.4 
are scheduled to ship in the summer of 1989. 


File System Enhancements (Product Manager: Steve Goldberg) 

Under investigation are several file system enhancements to support other projects, primarily New Finder and 
InterApplication Communication. These changes will not directly affect users, rather, users will only see improvements 
as Apple and developers take advantage of the new features. Among the possible enhancements are: the capability of 
locating a file even after it moves folders, a fast catalog search by file name, a public B-tree package, and a desktop 
manager which handles the additional file information currently stored in the Desktop file. 


Sound (Product Manager: Eileen Hart) 


Sew eeeveeeereee cere eee TT er 
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@ Product Plan for System Software 6.0.4 ; Page 1 


Macintosh 
Softy rate ala B 
Produ ct Plan fot’ 
System Software’ 6.0.4 
Codename: Antares 


Ken Feehan 
4-4567/Feehan1 


As information changes, this document will be updated and redistributed. 


Svstem Software Product Marketin 
4/6/89 


¢ Confidential Version 1.2 


€ Product Plan for System Software 6.0.4 | . Page 2 


This Product Plan provides detailed information related to the release of Macintosh 
System Software 6.0.4. 


EXECUTIVE SUMMARY 


Macintosh System Software 6.0.4 is a Product Support Release of System Software to 
support 2 new Macintosh computers: Esprit and Aurora. 


6.0.4 will be required when using Esprit or Aurora. 


6.0.4 will work with all Macmios Tapa Cuaisais with at least 1 shia a of 


It will not be necessary: for the inktalled base“of Macintosh’ users to upgrade to 
6.0.4. System Software 6:0:2;-6,0.3 arid-6.0.4 can | poexjst on networks. 


~“, 


6.0.4 will be included ‘with all Macintosh computers, dnd all System Software 
Update Kits as of announce date. ; : 


6.0.4 will be seheased with Esprit, dnd Aurofa, which are currently scheduled 
for August 1989 Telease. i 


6.0.4 will contain no new features for the installed base of Macintosh users. 
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Release Overview for 6.0.4 


Who needs 6.0.4? 
° 6.0.4 will be necessary when working with either Esprit or Aurora. 


6.0.4 will also offer limited additional functionality to applications using the Sound 
Manager (some priority 1 Sound Manager bugs will be fixed). 


n 4? 


¢ As a rule, the installed base does not need to upgrade to 6.0.4. 


6.0.2, 6.0.3 and 6.0.4. | 


irements for 


° 6.0.4 will run“onall Macintosh Plus or latér computers. 


Apple recommends a Hard disk “and/or two 800k floppies when using 6.0.2, 6.0.3 or 
6.0.4. All applications that’currently work with Systern'6.0.2/6.0.3 on a 1 megabyte 
Macintosh should also work with 6.0.4 and a 1 megabyte Macintosh. 


Schedule for 6.0.4: 


Availability of a golden master 6.0.4 is tied to the ROM schedule for Esprit and 
Aurora. If the schedule for either CPU slips, you should expect the 6.0.4 schedule to 
slip too. 


6.0.4 Alpha candidate: February 24th 
6.0.4 Beta candidate: May 5th 

6.0.4 Golden Master sign-off July 21st 
Esprit ROM Golden Master Late May ° 
Aurora ROM Golden Master June/July 
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vel m 


Apple should expect virtually all applications that operate properly with 6.0.2/6.0.3 to 
work with 6.0.4. 17 


Note: Whenever Apple releases new hardware, a very small percentage of 
applications do not work on the hardware. This is usually not related to the 
System Software and developers usually quickly revise their applications to work 
on the hardware. 


Leveewwceverweee eee ee eT TTT 


Pp nd 6.0.4: 


6.0.4 will be released with Esprit‘and Aufora and is to be in¢luded in all Esprit and 
Aurora Press Sneaks. \ ‘ ee 
6.0.4 will be announced at thie Spring Deyelopers Conference. 


As with the release of 6.0.3;Apple Will disclose as much’ detail about the actual 
changes as is appropriate. It is likely that the Press will have access to the changes in a 
similar level of detail as is outlined in the section entitled “Actual Changes" later in 
this report. 


The basic message for the Press will be: 


© 6.0.4 is the latest version of System Software and is required when using Esprit 
or Aurora. 


¢ 6.0.4 will work with all Macintosh computers with at least 1 megabyte of 
RAM. | 


e It is not necessary for the installed base of Macintosh users to upgrade to 6.0.4. 
System Software 6.0.2, 6.0.3 and 6.0.4 can coexist on networks. 
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¢ 6.0.4 will be included with all computers and all System Software Update Kits 
as of announce date. 


I for 6.0.4: 


¢ A new version of Script Manager will be available in Esprit and Aurora ROMs 
and a software version of this revised manager will be available for all 
Macintosh computers through 6.0.4. 


¢ the hook in System 6.0.3 for 32-Bit QuickDraw is still present in 6.0.4. 


The following projects will not be a part of 6.0.4: 

e¢ LaserWriter 6.0 

32-Bit QuickDraw.. 

AppleTalk 2.0 4 ; 

MultiFinder 6. 1 : qvevvevevereemvevvecewsvecwercerewl —«'“‘(‘i*‘“‘ézg;RS:«O#«C« gg PMMRAAAAAAARAANAOAGAAANGAAANAGEY f 
HD SC SetUp v 2, 0. senion aber may be e wong 
ASYNC SCSI ‘Manager. i 

the new Textldiy” : a 3 


¢ will a hook be placed in 6.0.4-for Bass? 


6.0.4 Risks: 
Yes there are some potential risks associated with this release. 

e Esprit and Aurora run at new clock speeds for Apple, and it is likely that 
during testing we may uncover some unforeseen problems. In the past 
Network & Communications products have been very sensitive to changes in 
clock speed. 


¢ 6.0.4 will be in testing concurrently with Big Bang. 
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ion of 6.0.4: 


6.0.4 will be available in all Macintosh CPUs and System Software Update Kits as of 
announce date. Apple will also send the disk set to the following people: 


2,000 retail computer stores 
400 Apple System Engineers (SEs) 
400 Apple Value Added Resellers (VARs) 
100 Higher Ed Marketing Service Reps (MSRs) 
__+100 Business Marketing Service Reps (MSRs) 
3,000 


Product Marketing should pueeet apprommalely $50,000 for this program. 
Evangelism will be responsible for the costs associated with | delivering the disk set to 
the certified developers 2 weeks babe 0 release. The ‘cost J. Ne program is 
approximately $100, 000. — - a 


6.0.4 will be available via: > 
e Compuserv ; 
e¢ AppleLink 
¢ Genie 
e User Groups 
e Apple's Software Subscription Program. 
¢ APDA 


er Manual Changes necessary for 6.0.4: 


Installer 3.0 will require a rewrite of chapter 9, “Startup Disks" of the "System 
Software User's Guide". 


The new disk configuration may require a revision to chapter 1, “Tutorial: 
Learning Macintosh Basics", in the "System Software Users Guide". 


The combination of Installer 3.0 and the new disk configuration will also require 
a substantial revision the ‘Open Me First’. 


System Software Product Marketin 
¢ Confidential Version 1.2 4/6/89 


@ Product Plan for System Software 6.0.4 Page 7 


Appendix A of the "System Software User's Guide, A History of Macintosh 
System Software" will also need to be revised to accommodate 6.0.2, 6.0.3, 
6.0.4, Macintosh IIx, SE/30, Cobra, Esprit, and Aurora. 


System Software extensions for Esprit, such as the Esprit ‘Battery’ Desk Accessory, 
are documented in the "Esprit User's Guide" and require no changes to the "System 
Software User's Guide." 


A schedule for the revised "System Software User's Guide" will be distributed world- 
wide in March. 


International and 6.0.4: 


All countries planning on-introducing Esprit or-Aurora-will-automatically be signed 
up for 6.0.4. An International Product Configuration Plan (IPCP) will go out in 
March. tend a a i i ay ra 


Seo Seve Tec err OeT ee eT STE E ETN 


Actual changes in 6.0.4: 


While every file on the disk set will be updated with the System Software 6.0.4 
version number, the only files that will actually change are the System file, Finder, 
MultiFinder, Installer, Monitors CDev, Calculator and Chooser DAs. 


The changes made to support Esprit are: 


System File: 

Modification to FKeys for Screen Shots 

revised snth resources 

revisions to itlb resource 

Esprit ROM patches 

a Script Manager bug fix for the "Wake-Up" feature 
Low Power alerts 

AppleShare alerts 
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Finder: 
¢ "Special" menu changed to include ‘Sleep’ 


New Control Panel Devices 
e Esprit CDev for control of contrast, RAM disk, Wake-Up and video output 


Calculator Desk Accessory 
e the Calculator will be updated to work with Esprit's numeric key pad 


New Desk Accessory 
e Battery for the control of power 


The changes made to 6.0.4 to support Aurora are: 
System File: ai j 

~ Aurora ROM patches ad bs 

e revised snth respurge~ aN ey “ 


Monitors Control Panél Devite ’ rs 
¢ Monitors will be- changed to work pith Aurgfas video 


The other changes to- 60. 4 are: i 

System File: ne eee asst 

¢ Gestalt-- the new Sea Environs 

¢ selected bug fixes to the Sound Manager 

e revisions to the Script Manager to further support localization. (word-breakage 
and accented characters) 


MultiFinder: 
¢ Change to support for future products 


Installer: 
¢ acompletely new Installer 


Responder: 
e updated to support Esprit and Aurora 
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isk Configuration of 6.0.4: 


6.0.4 will ship with 4 disks-- System Tools, Printing Tools, Utilities 1 and Utilities 2. 
Because there was no free space on System Tools disk, we have removed virtually all 
non-system Fonts and Desk Accessories from the System Folder on the System Tools 
and Utilities 1 disks. These Fonts and Desk Accessories are available on the Utilities 2 
disk and will be installed automatically by Installer 3.0. 


Apple USA has no plans to make 6.0.4 available on 1.4 meg floppies. 


System Tools Size approximately 750K 
System Folder 
Backgrounder 
-~Clipboard. filé? 
' DAHandler ; ; 
Finder. fu recente Version 6:4--—-» f 
| MultiFinder ™. version 6.04 ¢ 
‘Monitors, ‘ ey 
_-System File _—-version,®.0.4/ 
\ Fonts , 6 
eG Eneva 9, 12. pt 
~~ Monaco 9, 12 pt 
Desk Accessories 
Chooser 
Control Panel 
Esprit Patches 
Aurora Patches 
Teach Text 
Read Me 
Apple HD SC Setup 
Installer 3.0 
Installer 3.0 script 


> 


Printing Tools Size approximately 385K 
AppleTalk ImageWniter 
Image Writer version 5.2 
LaserWriter version 5.2 
LaserPrep 
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LaserWriter II SC 
PrintMonitor 

LQ ImageWriter : 

LQ AppleTalk ImageWriter 


Utilities #1 Size approximately 700K 
Apple HDSC Setup 
Disk First Aid 
HD BackUP 
Responder 
Teach Text 
System Folder 
Access Privileges 
~-A\ppleShare.™: 
| Clipboard File’ 
Color... ae 
| Esprit CDev_ 
| Finder. ‘ 
__ General ™ 
_KeyLayout 
f Keyboard: 
\, Monitors’ 
“Mouse _ 
Sound” 
Startup Device 
System 
Fonts 
Chicago 12 pt 
Geneva 9,12 pt 
Monaco 9, 12 pt 
Desk Accessories 
Chooser 
Control Panel 
Esprit Patch 
Aurora patches 


Utilities disk 2 Size approximately 775k 
Apple File Exchange Folder 
Apple File Exchange 
DCA-RFT/MacWrite 
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Font/DA Mover Folder 
Font/DA Mover 

Desk Accessories 
Alarm Clock 
Battery 
Calculator 
Chooser 
Control Panel 
Find File 
Key Caps 
Note Pad 
Puzzle 
i ae 

Beare tot 


peewee were ee ewe NT eT N EE Cee e 


aie “Caner 8 9; 10, 12, 14; ‘18 a pt 
worms. Genéya 10, 14, 18, 20, 24 pt 
‘, Helvetica 9, 10, 22, 14, 18, 24 pt 
:Londgn 18 pt / ; 
‘ | 4 Los Angeles 1b, 24 p 
See" Mobile 18 pty 
San Francisco 18 p pt. 
Symbol 9, 10, 12, 14, 18, 24 pt 
Times 9, 10, 12, 14, 18, 24 pt 
Venice 14 pt 
MacroMaker Folder 
MacroMaker 
MacroMaker Help 
Macros 
System Folder Additions Folder 
Color 
Esprit CDev 
Key Layout 
Keyboard 
Mouse 
Sound 
Map 
Close View 
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Easy Access 

Scrapbook file 

Startup device 
Appendix A: 
As of announce date, Apple will recommend the following System Software versions 
for the following Macintosh computers: 


System Software 6.0.2 60.3 6.0.4 


Macintosh Ix* ae 


Esprit 


* Macintosh ILx computers acting as AppleShare file servers 
should use System Software 6.0.3 or 6.0.4. 


Appendix B: Overview of Installer 3.0. 


Installer 3.0 is a completely rewritten version of Apple's System Software Installation 
program. Besides being significantly easier to use than the current Installer, Installer 
3.0 allows Apple to configure a Macintosh with a more complete System folder than 
we do currently. 


Installer 3.0 is intelligent. It can tell if it is installing on a new disk, or if it is 
updating a disk which contains a System folder. Installer 3.0 can also tell a floppy 
disk from a hard disk, and it knows what type of Macintosh it is installing on. The 
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installation script makes decisions as to what software should be installed based upon 
what Installer 3.0 knows about the Macintosh. 


Example #1: A customer wants to install 6.0.4 on an empty hard disk. Installer 3.0 
will install the following software: 
¢ all necessary System Software 
¢ all Printer Drivers 
¢ all appropriate Desk Accessories 
¢ all appropriate LaserWriter Fonts 


Example #2: A customer currently has System Software 5.0 on their hard disk and 
they want.to update to’6:0.4. Installer 3.0 will inventory their System 
folder and see the e following files: 


SOOM T CANN Tee ee See T TNS Te TEE TEE 
x 


System Binder 
Color _ ~ . MultiRinder 
General, °° “Easy Access 
LaserWriter LaserWriter Prep / 
AppleShare | ‘ AppleStare Prep/ 


Installer 3.0. will install fiew versions of all these files. Installer will in 
most cases not add any files to their System. 


Example #3: A customer wants to Install 6.0.4 on an 800k floppy. In this case, 
Installer 3.0 will install a System Folder and an ImageWriter printer 
driver on the Floppy. If the floppy does not have enough room, the 
user will be asked to insert an empty floppy. 
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Virtually of our customers will see the following 2 screens when they run Installer 3.0 


Welcome to the Apple Installer 


Your Macintosh needs certain software to start up. 


The Installer places this software on your 
disk in the System Be sere makes your —> > 
disk into a Startup. disk. . 


Easy Install chooses. the. sear Apple- pessesnienAs for 
your Macintosh, and: rea a startup disk f or ye 


(Use Custom, Install ifRyou ake sure vy fran to override 


those recommendations. ) 
| OK y 


This welcome screen is not finalized. The copy will be slightly reworked to address 
those users not installing on a blank disk. 


pease Software Product Marketing 


¢ Confidential Version 1.2 4/6/89 


@ Product Plan for System Software 6.0.4 Page 15 


The Easy Install screen is where the users will actually make a decision as to what 
drive they will install on, and also verify that the decisions made by the Installer are 
correct. 7 


Easy Install 


[pace oe seta 


ecoees pec ccscceces ces ons ces scenes coosnpoononscosoeoosoonennereane ces ceeces ene ees Feneen on ene eee cee ccovenccooooocore: 


| Click on Install to place: 

e Macintosh SE System Software 
Version6.0.4 : : 
e All Printer Software (Cinsten_) 
| © SE Hard DK gees 


£ ject Disk 
Switch Thsk 


POCCORHOCTeeLOREETEREEDOCOEDOSOSOHEOR OOD EOE DOLEOESS 


Pion 


Nee, Seen Tikal ane : an o.n0.0,0.0.0.0.0.8, ad 
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Installer 3.0 also contains the Custom Install option for those users looking for 
complete control over the installation process. 


Custom Install 


Mac I! Family System Software 

Macintosh SE System Software 

Macintosh Plus System Software ee 
Harpo System Software ae 

fiurora System Software 

Macintosh Family System Software 

Minimal Mac tl Family System-Software [| > SE Hard Disk 
Minimal Mac SE System sortulare : 
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